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PREFACE 





The Hewlett-Packard AdvanceNet is a set of hardware and software data communications 
products. One of these data communications products is DS/3000, an integrated software 
package that provides the capability of communication between HP computer systems. 


This manual documents DS/3000 as it applies to an HP 3000 network. The manual 
explains how an HP 3000 user can communicate with another (or several other) HP 3000 
computer systems by establishing a DS/3000 communications link. (Other manuals in the 
DS/ 3000 series document the other network combinations of computer types.) 


This manual explains the basic use of DS/3000 to users and programmers. A companion 
manual, the DS/3000 HP 3000 to HP 3000 Network Administrator Manual, explains more 
advanced concepts such as configuring a system, and using TRACE for debugging. 





Users of this manual should be familiar with the basic operating principles of the HP 3000 
computer system using the MPE operating system, and should also be familiar with the 
subjects covered in the following manuals: 


For MPE-IV (Versions not earlier than C.B1.A2): 


e HP 3000 Computer Systems, MPE Commands Reference Manual 
(30000-90009). 





e HP 3000 Computer Systems, MPE Intrinsics Reference Manual 
(30000-90010). 


¢ HP 3000 Computer Systems, System Manager/System Supervisor 
Reference Manual (30000-9001 4). 


e HP 3000 Computer Systems, Console Operator's Guide (32002-90004). 


For MPE-V/E (Versions not earlier than G.00.00): 





© HP 3000 Computer Systems, MPE V Commands Reference Manual 
(32033-90006) 


© HP 3000 Computer Systems, MPE V Intrinsics Reference Manual 
(32033-90007) 


© HP 3000 Computer Systems, MPE V System Operation and Resource 
Management Reference Manual (32033-90005) 
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PREFACE (continued) 


For both: 





e Fundamental Data Communications Handbook (5957-4634) 


e Data Communications Handbook, Section C, DS/ 3000 to 3000 
(32185-90003) 


e Data Communications Handbook, Section D, DS/3000 to 1000 
(32185-90006) 


e Data Communications Handbook, Section G, X.25 Link (32187-90006) 
For those users who also become involved in the selection and/or connection of the various 
network components, reference should be made to the appropriate component manuals, 


including the following: 


e HP 30010A Intelligent Network Processor (INP) Installation and | \ 
Service Manual (30010-90001). | 


e HP 30020A Intelligent Network Processor (INP) Installation and 
Service Manual (30020-90001). 


e HP 30020B Intelligent Network Processor (INP) Installation and 
Service Manual (30020-90005). 


e HP 30010A/30020A/B Intelligent Network Processor (INP) Diagnostic 
Procedures Manual (30010-90002). 





e HP 30055A Synchronous Single-Line Controlier (SSLC) Installation 
and Service Manual (30055-90001). 


e Hardwired Serial Interface (HSI) Installation and Service Manual 
(30360-90001). 


For those programmers who use other subsystems in conjunction with DS/3000, the 
following manuals should be referenced: \ 


e TurboIMAGE Reference Manual (32215-90050) 
e BASIC/3000 Interpreter Manual (30000-90026) 
e COBOL/II Reference Manual (32233-90001) 


e KSAM/3000 Reference Manual (30000-90079) 
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PREFACE (continued) 


NOTE 


Within the text of this manual, cross-references are 
made to these manuals by title. To obtain the part 
number of the referenced manual, refer to these lists 
of manuals in the Preface. 


In this release, DS/3000 and X.25 Link are two separate products. If you are using DS/3000 between 
HP 3000 computers, either with or without X.25, you should use this manual for all DS information 
and refer to the DS/ 3000 HP 3000 to HP 3000 Network Administrator Manual (32185-90002) for 
information about protocols, hardware, configuration, and tracing. If you are communicating with a 
PAD terminal or an HP 2334A Cluster Controller, refer to the X¥.25 Link for the HP 3000 Reference 
Manual (32187-90001). 
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NOTATION 


nonitalics 


ttalies 


[ ] 


{ } 


CONVENTIONS USED IN THIS MANUAL 


DESCRIPTION 


Words in syntax statements which are not in italics must be entered exactly as 
shown. Punctuation characters other than brackets, braces and ellipses must also 
be entered exactly as shown. For example: 


EXIT; 


Words in syntax statements which are in italics denote a parameter which must 
be replaced by a user-supplied variable. For example: 


CLOSE fzlename 


An element inside brackets in a syntax statement is optional. Several elements 
stacked inside brackets means the user may select any one or none of these 
elements. For example: 


ii User may select A or B or neither. 


When several elements are stacked within braces in a syntax statement, the user 
must select one of those elements. For example: 


A 
B User must select A or B or C. 
C 


A horizontal ellipsis in a syntax statement indicates that a previous element may 
be repeated. For example: 


[,ztemname]...; 


In addition, vertical and horizontal ellipses may be used in examples to indicate 
that portions of the example have been omitted. 


A shaded delimiter preceding a parameter in a syntax statement indicates that 
the delimiter must be supplied whenever (a) that parameter is included or (b) that 
parameter is omitted and any other parameter which follows is included. For 
example: 


means that the following are allowed: 
ittema 
ttema,itemb 


itema,itemb,iteme 
ttema,,iteme 
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CONVENTIONS (continued) 


underlining 


UTTSILELESTTISSTUTISTLET Testy I TieT) 
Boeeeeeerie 


CONTROL)CHar 


When necessary for clarity, the symbol A may be used in a syntax statement to 
indicate a required blank or an exact number of blanks. For example: 


SET [ (modifier) ]A(variable) ; 


When necessary for clarity in an example, user input may be underlined. For 
example: 


NEW NAME? ALPHA 


Brackets, braces or ellipses appearing in syntax or format statements which must 
be entered as shown will be underlined. For example: 


LET var[[subseript]] = value 
Output and input/output parameters are underlined. A _ notation in the 


description of each parameter distinguishes input/output from output 
parameters. For example: 


CREATE (parm? ,parm2,flags,error) 


Shading represents inverse video on the terminal’s screen. In addition, it is used to 
emphasize key portions of an example. 


The symbol (____) may be used to indicate a key on the terminal’s keyboard. 
For example, indicates the carriage return key. 


Control characters are indicated by followed by the character. For 


example, (CONTROL)Y means the user presses the control key and the character Y 
simultaneously. 
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SECTION 


INTRODUCING DS/3S000 





The Hewlett-Packard AdvanceNet is a combination of hardware and software products that make it 
possible for Hewlett-Packard computer systems to communicate with one another, and with IBM 
mainframes as well. The connections can be made over hardwired lines, and/or over the public 
telephone facility, and/or across Public Data Networks (PDNs), in any mixture. This capability, 
coupled with our proven remote entry capability to IBM computer systems, provides a total solution to 
large-company electronic data processing (EDP) needs. 


But exactly what does this overall capability mean? It means that a large multidivisional corporation 
can have a truly coordinated world-wide network of computer systems. They are coordinated in the 
sense of tying together the various commercial and industrial functions within each division and 
factory, and they are also coordinated in the larger sense of tying together the various divisions and 
factories at the corporate level. 


For example, imagine a large corporation which has factories in the United States, Canada, France, and 
West Germany. Within each factory there are HP 3000 computer systems performing such functions 
as inventory control, factory data collection, and operations management. With a Hewlett-Packard 
Distributed Systems Network these manufacturing information systems can be tied into an HP 3000 
system which handles the factory’s administrative functions (such as finance and accounting). The 
administrative systems of each factory can, in turn, be connected not only to one another but also (via 
remote job entry) to a large computer facility at corporate headquarters. This overall networking 
capability makes it possible to perform financial analysis and control at a group and corporate level as 
well as at the individual factories. 


Within the realm of AdvanceNet is the software subsystem that accomplishes HP computer-to-HP 
computer communication over these connecting lines. This software subsystem is called DS Network 
Services (DS/ 3000). Among other features, DS/3000 includes such capabilities as: 


e Virtual Terminal/Remote Command Execution. Gives the user remote interactive 
capabilities, even though the user’s terminal is physically connected to the local HP system. 


e Remote File Access. A user is allowed access to files in remote HP computer systems. An 
important aspect of this feature is the capability of using Interprocess Communications (IPC) 
between systems. 


® Remote Data Base Access. A user can directly access data bases on any remote HP computer 
under the same security protection used by local data bases. 


e Program-to-Program Communication. Permits programs residing in different HP computer 
systems to interactively exchange information with one another in a coordinated manner. 


e Network File Transfer. A facility that efficiently transfers disc files between HP 3000 
computer systems. 


This manual describes how an HP 3000 user can communicate with several HP 3000 computers by 
establishing a DS/3000 communications link. DS/3000 is that part of the HP Distributed Systems 
Network in which several HP 3000 computer systems are connected to one another. DS/3000 can 
also be used for intercomputer communications with other families of computers (such as HP 
3000/HP 1000, HP 3000/HP 250, and HP 3000/HP 98xx desktop computers), but these other 
combinations are described in separate reference manuals. 
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Introducing DS/3000 


As a simplified example of a computer network, imagine that you are in the same room with an HP 
3000 (labeled "System A" in Figure 1-1) and that another HP 3000 (labeled "System B") resides in 
another part of the building. These two computers are connected to one another by an 
interconnecting cable and a pair of communications interfaces. By virtue of DS/3000 you can use the 
processing capability of both of these HP 3000 machines and pass data back and forth between them 
by entering commands through a single terminal. 


To see how DS/3000 works in this simple example, follow through the step-by-step procedure. 


HP3000 Communications HP3000 
SYSTEM A Interface SYSTEM B 
Interconnecting 
Cable 


Figure 1-1. HP 3000 to HP 3000 Example 
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Step 1. Sit down at a terminal connected to System A and initiate a session. 


:HELLO_USER. ACCOUNT 


HP3000 / MPE V_ G.02.00. MON, SEP 30, 1985, 12:23 PM 
WELCOME TO SYSTEM A. 


Within the context of DS/3000, such a session is referred to as a "local" session because it is active 
within the HP 3000 to which your terminal 1s directly connected. This terminology becomes more 
meaningful later, since all you have actually done, so far, is initiate a standard MPE session. At this 
point, you have reached the situation illustrated in Figure 1-2. 


HP3000 Communications HP3000 
SYSTEM A Interface SYSTEM B 





Interconnecting 
Cable 





Figure 1-2. Initiating the Local Session 
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Step 2. Now, open a communications line between System A and System B. Do this by entering a 
:DSLINE command. 


:DSLINE REMOTE1 
OS LINE NUMBER = #L3 


In this example, REMOTE1 is the DS device class name established during system configuration (in 
System A) for the particular line you wish to use. DS/3000 opens the line and then assigns you a line 
number (3 in this example). This line number is analagous to the file number returned to you by the 
MPE File System when you open a file programmatically using the FOPEN intrinsic. Within your local 
session, it uniquely identifies the particular line that you have opened. This becomes significant only 
if you must open more than one communications line during a session. 


Step 3. Now that you have acquired access to a communications line between System A and System B, 
initiate a session in System B (from your local log-on terminal). Do this by entering a REMOTE 
command which includes an MPE HELLO command for the remote system. 


:REMOTE HELLO RUSER.RACCOUNT 
HP3000 / MPE V_ G.02.00. MON, SEP 30, 1985, 12:23 PM 


WELCOME TO SYSTEM B. 


Within the context of DS/3000, this type of session is referred to as a "remote" session because it is 
active within the remotely located HP 3000 that is connected indirectly to your log-on terminal by 
way of a communications line and your local HP 3000. You now have two distinct sessions in progress 
concurrently: one in System A (under the user and account names USER. ACCOUNT) and the other in 
System B (under the user and account names RUSER.RACCOUNT). It is important to keep in mind that 
within System A your local session is operating under the capabilities and security restrictions defined 
(by the accounting structure of System A) for USER.ACCOUNT, while within System B your remote 
session is operating under the capabilities and security restrictions defined (by the accounting structure 
of System B) for RUSER.RACCOUNT. At this point, the situation is as illustrated in Figure 1-3. As will 
be seen in the next few steps, you can alternate freely between the two sessions. 
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HP3000 Communications HP3000 
SYSTEM A Interface SYSTEM B 


SESSION SESSION 





Interconnecting 
Cable 





Figure 1-3. Initiating the Remote Session 


Step 4. Now, see what files reside in the home group of the ACCOUNT account in System A. 

: LISTF 

FILENAME 

DATA1 DATA3 FILE1 SOURCE2 SOURCES 
You can do the same for the home group of the RACCOUNT account in System B by entering the 
following command through the same terminal: 

:REMOTE LISTF 

FILENAME 


DATAt DATAS DATA6 FILE3 SOURCE 1 


Notice that in both cases the same command was entered, but in the latter case the prefix REMOTE was 
used. The presence or absence of that prefix is what determines whether a command is to be executed 
in the local session or in the remote session. 
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Step 5. Asa result of the LISTF and REMOTE LISTF displays, you can see that a source file, named 
SOURCE 1, exists in System B but not in System A. Suppose you wish to modify one of the statements 
in that program. To do that, use the text editor in System B. This time, instead of prefixing your 
remote commands with REMOTE, try a different technique. Enter the following: 


: REMOTE 
# 


This construct gets into the remote session in such a way that all commands can be entered in their 
normal form (without the prefix REMOTE). The # is the prompt character issued by DS/3000 (in place 
of the usual MPE colon prompt). In all other respects it will seem as though you are executing an 
MPE interactive session on your local computer. 


Step 6. Now invoke the text editor, copy the content of SOURCE! (which is a file in System B) into 
the editor’s work file, display the content of the work file, modify the desired statement, and store the 
altered source code back in SOURCE 1. 


#EDITOR 
HP32201A.7.17 EDIT/3000 WED, MAR 6, 1985, 3:47 PM 
(C) HEWLETT-PACKARD CO. 1985 
/SET FORMAT=COBOL 
/T SOURCE1 
/LIST ALL 

1 $CONTROL USLINIT, SOURCE 
IDENTIFICATION DIVISION. 
PROGRAM-ID. COBOL-TEST1. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 EDIT-FIELD PIc $$$$$9.99. 
77 TOTAL-COST PIC 999V99. 
77 COST-OF-SALE PIC 99V99. 
(7 TAX PIC 99V99. 


it 

2 

3 

4 

5 

6 

¢ 

8 

9 

¢ ‘ 

1 PROCEDURE DIVISION. 

2 ENTER-ROUTINE. 

-3 MOVE ZEROS TO TOTAL-COST. 
4 DISPLAY SPACE. 

5 DISPLAY "ENTER COST OF SALE”. 

6 ACCEPT COST-OF-SALE. 

7 COMPUTE TAX = COST-OF-SALE * .06. 

8 ADD COST-OF-SALE, TAX TO TOTAL-COST. 
-9 MOVE TOTAL-COST TO EDIT-FIELD. 
DISPLAY "TOTAL COST= " EDIT-FIELD. 

1 DISPLAY "ARE YOU FINISHED? (Y OR N)”. 
2 ACCEPT Y-N. 

.3 IF Y-N = "N" OR "n" GO TO ENTER-ROUTINE. 
-4 STOP RUN. 


1-6 


























Introducing DS/3000 


/MODIFY 2.5 
MODIFY 2.5 
DISPLAY "ENTER COST OF SALE". 
I (NO DECIMAL POINT) 
DISPLAY "ENTER COST OF SALE (NO DECIMAL POINT)”. 


/KEEP_SOURCE1 

SOURCE! ALREADY EXISTS - RESPOND YES TO PURGE OLD AND KEEP NEW 
PURGE OLD? YES 

/EXIT 


END OF SUBSYSTEM 
# 


Step 7. The work in System B is now completed; so terminate the remote session and return control to 
your local session. 


#BYE 


CPU=4. CONNECT=7. WED, MAR 6, 1985, 9:15 AM 
#; 


Note that you are now back in the local session in System A (signified by the colon prompt). The 
remote session no longer exists, but the communications line is still open. You could, if you wanted, 
initiate another remote session over the line by issuing another REMOTE HELLO command. To close 
the communications line, enter the following variation of the :DSLINE command: 


:DSLINE REMOTE1 ;CLOSE 

1 DS LINE WAS CLOSED. 
Finally, terminate the local session. 

: BYE 


CPU=1. CONNECT=11. WED, MAR 6, 1985, 9:16 AM 
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SECTION 


THE COMMUNICATIONS LINK 





WHAT IS A COMMUNICATIONS LINK? 


Within the context of DS/3000, a "communications link" consists of the following elements: 
e An interactive session in progress on an HP 3000 computer. 


e A physical communications line between that HP 3000 computer and another HP 3000 computer 
at a remote location. 


e An interactive session 1n progress in the remote HP 3000 computer (initiated over the physical 
communications line from your local session). 


Note that your local terminal is the log-on terminal for both the local session and the remote session. 
(See Figure 2-1.) 





HP3000 HP3000 


— 
SESSION _ — SESSION 








Communications Line 





Log-on 
Terminal 


Figure 2-1. DS/3000 Communications Link (HP 3000 to HP 3000) 





The Communications Link 
OPENING A LINE 


A communications link can be established over a hardwired communications line, over the public 
telephone network, or over an X.21 or X.25 Public Data Network (PDN). The procedures for opening 
hardwired lines and for opening telephone lines differ only slightly. Therefore, the basic differences 
will be presented first, followed by the procedures that are essentially the same. Generally, once the 
connection to the remote computer is established, you will perceive no difference in the way DS/3000 
performs. 


Opening a Hardwired Line 


What is a hardwired line? In the general field of data communications there are two types of lines 
commonly referred to as "hardwired." The first type is a dedicated path on the public telephone 
network that 1s leased from the telephone company for the private use of a computer-to-computer 
configuration. Such a line serves as a permanent connection between the two computers. The other 
type of hardwired line is a cable that is connected directly to the communications I/O interfaces of 
the two computers. Within the context of DS/3000, "hardwired" always refers to a cable connection. 
However, the technique for opening a line is the same for either a direct-connect line or a leased 
(nonswitched) telephone line. 


The hardwired interconnecting cable connects to each HP 3000 by way of a communications 
interface. The communications interfaces that can be used for a hardwired connection are listed in 
Table 2-1. Although the INPs and the SSLC are the interfaces most commonly used for telephone line 
connections with modems, they can also be used in hardwired applications without modems. Refer to 
Table 2-1 to see which controller is used with which HP system. 


Table 2-1. Associations between Controllers and Systems. 


HP 3000 Series II/III 


HP 30010A 
Intelligent Network Processor (INP) 


HP 30020A HP 3000 Series 30/33/39/40/42/44/48 
Intelligent Network Processor 


HP 30020B HP 3000 Series 
Intelligent Network Processor 30/33/39/40/42/44/48/64/68 


HP 30055A HP 3000 Series II/III 
Synchronous Single-Line Controller (SSLC) 


HP 30360A HP 3000 Series II/III 
Hardwired Serial Interface (HSI) 
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Opening a Line 


It is relatively straightforward to obtain access to a hardwired communications line. All you are 
required to do is identify the particular communications interface you wish to use. 


NOTE 


Throughout this manual, the term "dsdevice" will be used 
as a generic term for logical device number, class name 
or, in the case of X.25, a node name. 


You identify the particular communications interface of the particular line you wish to use by 
specifying the dsdevice associated during system configuration with the desired interface. In the 
example in Section 1, the : DSLINE command was used for this purpose, as follows: 


:DSLINE REMOTE1 


If you are the first person to use a :DSLINE command after the operator has enabled the DS line, you 
may also wish to specify the size of the DS/3000 line buffer to be used in conjunction with the line. 
The size of this buffer determines the maximum amount of data that can be sent or received in a 
single physical transmission over the line. Note that a transmission as you normally think of it 
(sending or receiving all or part of a file) may actually consist of many physical transmissions. In 
essence, this buffer size defines a blocking factor for the line. (See Figure 2-2.) A default buffer size is 
established during system configuration, and in most cases (as in the example in Section 1), you will 
find it satisfactory to let this default value prevail. If you do wish to change the line buffer size, use 
the Linebuf parameter as described on pages 2-17 and 2-18. 
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Assume that the DS/3000 line buffer size is 512 words and that the user has initiated the 
transmission of a block of data 1200 words in length from an HP 3000 to a remote HP 3000. The 
block of data would actually be sent in three separate transmissions, as follows. (DS/3000 appends an 
average of 20 words of overhead on each transmission.) 


1200 words of data to 
be transmitted 


First physical 
transmission: 512 
words (492 words of 
data + 20 words of DS 
overhead) 


Second physical 
transmission: 512 
words (492 words of 
data + 20 words of DS 
overhead ) 


Third physical 
transmission: 236 
words (216 words of 
data + 20 words of DS 
overhead) 


1200 words of data 
received at remote 
computer 


Figure 2-2. DS/3000 Line Buffer Example 


When you enter a :DSLINE command, DS/3000 attempts to give you access to the specified 
communications line and, if successful, informs you of the assigned DS line number by displaying the 
following message at your terminal: 


DS LINE NUMBER = #Lx 
where x is the assigned DS line number. In the example in Section 1, the DS line number "3" was 
assigned. The DS line number is significant only if you open and use more than one communications 
line concurrently within a single local session (see "Opening Multiple Lines" later in this section). 
At this point you have acquired a physical communications line but the communications link does not 


yet exist. The actual communications link between the two computers is established by initiating a 
remote session over the line. You do this by executing a REMOTE HELLO command. In the example in 
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Opening a Line 


Section 1, the REMOTE HELLO command contained the minimum parameters required (a username and 
an accountname), as follows: 


:REMOTE HELLO RUSER.RACCOUNT 


The communications link between the two HP 3000 computers now exists. 


Opening a Telephone Line 


A DS/3000 communications link can also be established over the public (dial-up) telephone network. 
In such a case, the information passed back and forth between the two computers travels over the 
same lines that are used for normal voice traffic. Each computer is interfaced to the telephone lines 
by way of a modem. (The term "modem" is a contraction of MOdulator-DEModulator.) A modem is a 
device that translates digital signals (electrical impulses) generated by a computer into analog signals 
(tones) that can be transmitted over telephone lines, and vice versa. 


The modem is connected to the HP 3000 Computer System by way of a communications interface. 
The communications interfaces used with modems are listed in Table 2-2. Refer to Table 2-2 to see 
which controller is used with which HP system. Each INP or SSLC controls one modem (such as an HP 
37210T, 37220T, or 37230A modem, or a Bell System Type 201, 208, or 209 modem), and is capable 
of both initiating and accepting a telephone connection with a remote computer over the public 
telephone network or a leased telephone line. 


Table 2-2. Associations between Controllers and Systems. 


HP 30010A HP 3000 Series I/II 
Intelligent Network Processor (INP) 


HP 30020A HP 3000 Series 30/33/39/40/42/44/48 
Intelligent Network Processor 


HP 30020B HP 3000 Series 
Intelligent Network Processor 30/33/39/40/42/44/48/64/68 


HP 30055A HP 3000 Series II/IIl 
Synchronous Single-Line Controller (SSLC) 





Opening a Line 


It is a little more complex to obtain access to a telephone line than to a hardwired line. First, you 
must identify the particular communications interface (INP or SSLC) you wish to use. You do this by 
specifying the device class name or logical device number of the communication line that was 
associated during system configuration with the desired interface. You use the :DSLINE command for 
this purpose, as follows: 


:DSLINE REMOTE2 


If you are the first person to use a :DSLINE command after the operator has enabled the DS line, you 
may also wish to specify the size of the DS/3000 line buffer to be used in conjunction with the line. 
The size of this buffer determines the maximum sized block that can be sent or received in a single 
physical transmission over the line. Note that a transmission as you normally think of it (sending or 
receiving all or part of a file) may actually consist of many physical transmissions. In essence, this 
buffer size defines a blocking factor for the line. (See Figure 2-2.) A default buffer size is established 
during system configuration, and in most cases (as in the example in Section 1), you will find it 
satisfactory to let this default value prevail. If you wish to change the line buffer size, use the 
Linebuf parameter as described on pages 2-17 and 2-18. 


Next, you may wish to supply a set of identification (ID) sequences to be used in verifying that the 
desired pair of computers are connected to one another. This is discussed under "ID Sequences" later in 
this section. Briefly, however, you may supply an ID sequence that identifies your HP 3000 and one 
or more ID sequences that identify the remote computer with which you wish to be connected. When 
a telephone connection is established between your HP 3000 and a remote HP 3000, the two 
computers exchange ID sequences and their validity determines whether or not the connection is to 
remain in effect. You use the :DSLINE command to supply ID sequences, as follows: 


:DSLINE REMOTE2 ;LOCID="SYSTEM A" ;REMID="SYSTEM X”" 


where SYSTEM A is the ID sequence identifying your local HP 3000 and SYSTEM X is the ID sequence 
identifying the remote computer with which you want to establish a telephone connection. 


Again, there are default values that can be established during system configuration. In most cases, 
however, you will at least want to explicitly identify the desired remote HP 3000 to be certain that 
the proper connection is being established. 


Now you must establish the physical connection between the two computers by dialing (at the modem) 
the telephone number of the remote computer and responding (at the system console) to the dial 
request. If you wish to have the console operator of your HP 3000 dial the number for you, you may 
supply the desired number in the :DSLINE command and it will be displayed as part of a dial request 
message at the operator’s console. In such a case, you would supply the telephone number as follows: 


:DSLINE REMOTE2 ;LOCID="SYSTEM A" ;REMID="SYSTEM X" ;PHNUM=555-1234 


If autodial equipment is installed on the REMOTE2 line, the telephone number supplied in the 
:DSLINE command is used instead of the number configured for the line. 


The various possibilities involved in establishing a telephone connection with a remote computer are 
discussed under "Dialing the Remote Computer" later in this section. 


When you execute the :DSLINE command, DS/3000 attempts to give you access to the specified 
communications interface (INP or SSLC) and, if the telephone connection is successfully established, 
informs you of the assigned DS line number by displaying the following message at your terminal: 


DS LINE NUMBER = #Lx 


Opening a Line 


where x is the assigned DS line number. In the example in Section 1, the DS line number "3" was 
assigned. The DS line number 1s significant only if you open and use more than one communications 
line concurrently within a single local session (see "Opening Multiple Lines" later in this section). 





At this point, you have acquired a physical communications line, but the communications link does not 
yet exist. The actual communications link between the two computers is established by initiating a 
remote session over the line. You do this by executing a :REMOTE HELLO command. In the example 
in Section 1,a :REMOTE HELLO command was used that contained the minimum parameters required 
(a username and an accountname), as follows: 


:REMOTE HELLO RUSER.RACCOUNT 


The communications link between the two HP 3000 computers now exists. 
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Specifying a DS Line 


As you have seen, in order to open either a hardwired communications line or a dial-up telephone line, 
you must specify a dsdevice identifying the particular communication line that is associated with the 
specific interface you wish to use. Deciding which name and number to use is complicated, but in real 
life, once the hardware and software configuration is installed and usable, most DS/3000 sites will 
post a notice defining all of the available communications lines and the proper device class names, 
logical device numbers, or nodenames for each. The following examples describe the procedure in case 
you wish to know how it works, or if your system does not post them. 


For each communications interface, there is a pair of associated drivers. First, there is the actual INP, 
HSI, or SSLC driver that directly controls the operation of the interface board. In addition, there is a 
DS/3000 communications driver that controls the operation of the INP, HSI, or SSLC driver. The 
names of these drivers are as follows: 


IOINPO (INP driver) 

CSHBSCO (HSI driver) 

CSSBSC0 (SSLC driver) 

IODSO (DS/3000 communications driver, while utilizing the bisync protocol) 

IODSX (DS/3000 communications driver, while utilizing the X.25 Link software) 
IODSTRMO (DS/3000 virtual terminal driver, while utilizing the bisync protocol) 
IODSTRMX (DS/ 3000 virtual terminal driver, while utilizing the X.25 Link software) 


Now look at the appropriate sample I/O device table produced during system configuration. (See 
Figures 2-3 and 2-4 for a hardwired line or Figures 2-5 and 2-6 for a telephone line). 


One or more virtual terminal drivers (IODSTRMO or IODSTRMX) are also configured into a system. 
The IODSTRMO/IODSTRMxX entries allow users on another system to be logged on to a system and 
regulate the number of remote Session Main Processes (SMP) that can be assigned to a given line. Each 
IODSTRMO/IODSTRMxX entry is related to the proper communications interface entry by the number 
specified in the column labeled DRT. Figure 2-4 (the INP hardwired example) shows logical device 67 
paired with logical device 27; Figure 2-6 (the INP telephone line example) shows logical device 68 
paired with logical device 26. 


In Figure 2-3, notice that the HSI board entries (logical devices 12 through 15) look the same except 
for the PORTMASK. The PORTMASK specifies which port on the board is to be used. There are also 
virtual terminals (logical devices 60 through 64) referencing back to logical device 12. Since only one 
port on the HSI board can be opened at a time, only one block of virtual terminal entries is needed for 
that board. As each port is opened individually by specifying the corresponding dsdevice in the 

: DSCONTROL command (see Section 9), the system automatically reallocates the virtual terminal 
entries to the proper HSI board entry. This reallocation will not, however, show up in the I/O 
configuration table. This use of virtual terminals is unique to the HSI. SSLC and INP configurations 
require a block of terminals for each interface configured. 


In Figure 2-3, the shaded items in the column labeled DRIVER NAME show four HSI lines (CSHBSCO) 
configured into the system as logical devices 12 through 15. For each one of these lines, there is a 
DS/3000 communications driver, IODSO, also configured into the system. Each IODSO entry is related 
to the proper HSI entry by the number specified in the column labeled DRT (the # prefix indicates a 
back reference to a previously defined logical device number). Logical devices 50 through 53 are 
paired with logical devices 12 through 15, respectively. In this example, it is the device class name or 
logical device number of the appropriate IODSO entry that would be used to specify the desired line. 
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Figure 2-3, Sample I/O Device Table (Hardwired Line with HSI) 
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LOG DRT U CT SUB REC OUTPUT MODE DRIVER DEVICE 
DEV # N HY TYPE TERMINAL WIDTH DEV NAME CLASSES 
# I AP TYPE SPEED 
T NE 
1 4 0 00 6 128 0 IOMDISC1 SPOOL 
SYSDISK 
e 5 0 00 3 128 0 IOMDISCO DISC 
5 13 0 08 0 40 LP JA IOCRDO CARD 
6 14 0 0 322 66 0 TOPRTO LP 
€ 6 O 0 240 128 LP IOTAPEO TAPE 
8 6 1 O 24 0 128 LP IOTAPEO TAPE 
9 6 2 0 240 128 LP IOTAPEO TAPE 
10 6 3 0 240 128 LP JA IOTAPEO BATAPE 
11 20 0 O 340 128 0 TOPTPNO PT PUNCH 
A: 6 0 019 3 0 0 at Ba HST1 
0 019 3 0 0 HSTe2 
0 019 3 0 0 HSI3 
0 019 3 0 0 JoHBSCOQO HSI4 
0 0 16 0 10 ?? 40 20 JAID IOTERMO CONSOLE 
1 0 16 0 11 2? 40 21 JAID IOTERMO TERM 
2 0160 11 2? 40 22 JAID IOTERMO £TERM 
3 0 160 11 ?? 40 23 JAID JIOTERMO TERM 
4 0 160 wi. cae 40 24 JAID IOTERMO TERM 
5 O 16 1 11 2? 40 25 JAID IOTERMO TERM 
0 017 0 0 0 IOINPO INP 1 
0 017 3 0 0 IOINPO INP2 
0 0 180 0 0 lated SSLC2 
0 O 41 0 128 0 HDS 1 
0 O 41 0 128 0 HDS2 
0 O 410 128 0 HDS3 
0 0 41 0 128 0 HDS4 
0 0 16 0 ag 0 40 60 J 1D DSTERM 
0 0 16 0 oe te 40 61 J ID DSTERM 
0 0 16 0 te 2a 40 62 J ID OSTERM 
0 0 16 0 ae Ue 40 63 J ID OSTERM 
0 0160 =??? ?? 40 64 J ID DSTERM 
0 O 41 1 128 0 DSLINE4 
0 O 41 1 128 0 DSLINE2 
0 0160 ?? ?? 40 68 J ID IODSTRMO' INP1 
0 0160 ?? ?? 40 69 J ID JIODSTRMO INP2 
O QO 41 0 a4 128 0 TODSO SDS 1 
0 0160 ?? ?? 36 71 J ID JODSTRMO DSTERM 
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In Figure 2-4, the shaded items in the column labeled DRIVER NAME show an INP (IOINPO) 
configured into the system as logical device 27. (Note that the subtype is 3, indicating hardwired.) 
For this line, there is a DS/3000 communications driver (IODSO) also configured into the system. The 
IODSO entry is related to the proper INP entry by the number specified in the column labeled DRT 
(the # prefix indicates a back reference to a previously defined logical device number). Logical device 
67 is paired with logical device 27. In this example, it is the device class name (DSLINE@) or logical 
device number (67) of the IODSO entry that would be used to specify the desired line. 


NOTE 


Figure 2-4 does not show a line configured for X.25 
activity to another HP 3000. The back referencing 
scheme is identical to this example. However, the 
following differences should be noted for an X.25 
configuration: 


e The communications driver is named IODSX. 


e The device class name or logical device number of an 
IODSX entry should not be used in a :DSLINE 
command (or in other commands, such as DSCOPY). 
To access the desired remote node, we encourage 
X.25 Link users to enter a nodename whenever a 
dsdevice is required. See page 2-16 to determine a 
node name. 
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LOG DRT U CT SUB REC OUTPUT MODE ORIVER DEVICE 
DEV # N HY TYPE TERMINAL WIDTH DEV NAME CLASSES 
# I AP TYPE SPEED 
TONE 
1 4 000 6 128 O IOMDISC1 SPOOL 
SYSDISK 
0 00 3 128 0 IOMDISCO DISC 
0 08 O 40 LP JA IOCRDO —- CARD 
0 0 322 66 0 IOPRTO  ~—LP 
0 0240 128 LP IOTAPEO TAPE 
1 0240 128 LP IOTAPEO TAPE 
2 0 240 128 LP IOTAPEO TAPE 
3 0240 128 LP JA IOTAPEO BATAPE 
0 0340- 128 0 IOPTPNO = PTPUNCH 
00193 0 ) CSHBSCO —-HSI1 
0 0193 0 ) CSHBSCO —-HSI2 
0 0193 0 0 CSHBSCO 4HSI3 
0 0193 0 ) CSHBSCO HSI4 
00160 10 ?? 40 20 JAID IOTERMO CONSOLE 
10160 11 2? 40 21 JAID IOTERMO TERM 
20160 11 2 40 22 JAID IOTERMO TERM 
3 0160 11 2? 40 23 JAID IOTERMO TERM 
40160 11 2? 40 24 JAID IOTERMO TERM 
5 0161 11 2? 40 25 JAID IOTERMO TERM 
0 0170 0 ) IOINPO —sINP'1 
0 0173 0 ) TOINPO  =——INP2 
0 0180 0 0 CSSBSCO SSLC2 
0 0 410 128 0 IODSO HDS1 
0 0 410 128 0 IODSO HDS2 
0 0410 128 0 IODSO HDS3 
0 0410 128 0 IODSO HDS4 
0 0160 ?? 2? 40 60 J ID  IODSTRMO DSTERM 
0 0160 7? 2? 40 61 J ID  IODSTRMO DSTERM 
0 0160 ?2 2? 40 62 J ID  IODSTRMO DSTERM 
0 0160 ?? 2? 40 63 J ID IODSTRMO DSTERM 
0 0160 ?? 2? 40 64 J ID  IODSTRMO DOSTERM 
00160 ?? 2? 40 65 J ID  IODSTRMO DSTERM 
0 0411 128 0 IODSO DSLINE1 
0 0411 128 0 TODSO DSLINE2 
0 0160 ?? 2? 40 68 J ID IODSTRMO INP 
0 0160 ?2? 2 40 69 J ID YODSTRMO INP2 
0 0 410 2? 128 0 IODSO SDS1 
0 0160 72? 2 36 71 J ID  IODSTRMO DSTERM 





Figure 2-4, Sample I/O Device Table (Hardwired Line with INP) 


Opening a Line 


In Figure 2-5, the shaded items in the column labeled DRIVER NAME show one SSLC (CSSBSCO) 
configured into the system as logical device 29. (Note that the subtype is 0, indicating a switched 
telephone line.) Notice the DS/3000 communications driver, IODSO, is related to the SSLC entry by 
the number specified in the column labeled DRT (the # prefix indicates a back reference to a 
previously defined logical device number). Logical device 70 is paired with logical device 29. It is the 
device class name (SDS1) or logical device number (70) of the IODSO entry that would be used to 
specify the desired line. 


























LOG DRT U CT SUB REC 

DEV # N HY TYPE TERMINAL WIDTH 

# I AP TYPE SPEED 
T NE 

1 4 0 00 6 128 
0 00 3 128 
0 08 0 40 
0 0 322 66 
0 0 240 128 
1 0 240 128 
2 0 240 128 
3 0240 128 
0 0 340 128 
0 019 3 0 
0 019 3 0 
0 019 3 0 
0 0 19 3 0 
0 0 16 0 10 %? 40 
1 0160 Wie t? 40 
2 0 16 0 11 ?? 40 
3 0160 11 «2? 40 
4 0 16 0 a. ce 40 
5 O 16 1 11 «2? 40 
0 0170 0 
0 017 3 0 
0 0180 0 
0 O 41 0 128 
0 O 41 0 128 
0 0 41 0 128 
0 O 41 0 128 
0 0 16 0 ane ar 40 
0 0 16 0 ae. ee 40 
0 O 16 0 ar te 40 
0 0 16 0 C7 32 40 
0 0160 =?? ?? 40 
0 0160 ?? ?? 40 
0 O 41 1 128 
0 O 41 1 128 
0 0160 ee ae 40 
0 QO 16 0 ce 28 40 
0 O 41 0 ?? 128 
0 0 16 0 a¢ oe 36 
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Figure 2-5. Sample I/O Device Table (Telephone Line with SSLC) 
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DEVICE 
CLASSES 


SPOOL 
SYSDISK 
DISC 
CARD 

LP 
TAPE 
TAPE 
TAPE 
BATAPE 
PTPUNCH 
HST1 
HSI2 
HSI3 
HS14 
CONSOLE 
TERM 
TERM 
TERM 
TERM 
TERM 
INP1 
INP2 
SSLC2 
HDS 1 
HDS2 
HDS3 
HDS 4 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSLINE1 
DSLINE2 
INP 1 
INP2 
SDS 1 
DSTERM 


Opening a Line 


In Figure 2-6, the shaded items in the column labeled DRIVER NAME show an INP (IOINPO) 
configured into the system as logical device 26. (Note that the subtype is 0. This indicates that the 
INP is used for a dial-up line.) For this line, there is a DS/3000 communications driver, IODSO, also 
configured into the system. The IODSO entry is related to the proper INP entry by the number 
specified in the column labeled DRT (the # prefix indicates a back reference to a previously defined 
logical device number). Logical device 66 is paired with logical device 26. It is the device class name 
(DSLINE1) or logical device number (66) of the IODSO entry that would be used to specify the desired 
line. 








LOG DRT U 
DEV # 
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C T SUB REC 
H Y TYPE TERMINAL WIDTH 
A P TYPE SPEED 
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00 6 128 
00 3 128 
08 0O 40 
0 32 2 66 
0 24 0 128 
0 240 128 
0 24 0 128 
0 24 0 128 
0 34 0 128 
0 19 3 0 
019 3 0 
019 3 0 
019 3 0 

0 16 0 10 62? 40 
0 16 0 11 2? 40 
0 16 0 11 ?? 40 
0 16 0 ie oe8 40 
0 16 0 11 2? 40 
0 16 1 11 2? 40 
017 0 0 

0 17 3 0 

0 18 0 0 

0 41 0 128 
0 41 0 128 
0 41 0 128 
0 41 0 128 
0160 ?? ?? 40 
0160 ?? ?? 40 
0160 ?? ?? 40 
0 16 0 oe ae 40 
0 16 0 a aa Se 6 40 
0 16 0 ce 27 40 
0 41 1 128 
0 41 1 128 
0160 ?? ?? 40 
0160 ?? ?? 40 
0 41 0 oe 128 
0 16 0 G2 6 36 
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Figure 2-6. Sample I/O Device Table (Telephone Line with INP) 
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DEVICE 
CLASSES 


SPOOL 
SYSDISK 
DISC 
CARD 

LP 
TAPE 
TAPE 
TAPE 
BATAPE 
PT PUNCH 
HST1 
HST2 
HSI3 
HST4 
CONSOLE 
TERM 
TERM 
TERM 
TERM 
TERM 
INP1 
INP2 
SSLC2 
HDS 1 
HDS2 
HDS3 
HDS4 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSTERM 
DSLINE1 
DSLINE2 
INP1 
INP2 
SDS 1 
DSTERM 


Opening a Line 


If you have only one communications interface configured into your system, there is no question about 
which name or number to specify ina :DSLINE command. If there is more than one communications 
interface, however, you must know (or ask someone who knows) which interface is connected to the 
physical line you want to use. 


Specifying an X.25 Line 

When specifying an X.25 line, you do not use the I/O device table. This is because X.25 uses node 
names, rather than LDEVs, to specify devices. To find out what node names are configured on your 
system, type the following: 

:RUN NETCONF .PUB.SYS 

LIST 


See the DS/ 3000 HP 3000 to HP 3000 Network Administrator Manual for more information on 
NETCONF. 





:DSLINE 


The DSLINE Command 





The format of the :DSLINE command, as used to open a line, is presented here. In addition to opening 
a hardwired line or a telephone line, this command can also be used for closing one or more 
communications lines (see page 2-50). 


SYNTAX 


:DSLINE dsdevice [;LINEBUF=buffersize] 
;EXCLUSIVE] 


[ 

[ 

[ ;COMP] 
[;NOCOMP] 
[;QUIET] 
[ 
[ 
[ 


> 
; PHNUM=tel ephonenumber | 

; LOCID=localidsequence] 
;REMID=remoteidsequence[,...remoteidsequence] ] 
[;SELECT=selecttonsignal sequence] 

[OPEN ] 

[ ;QUEUE] 

[ ;NOQUEUE] 








PARAMETERS 


The parameters that pertain to opening a line follow: 


dsdevice This is the device class name or logical device number assigned to the 
DS/3000 communications driver (IODSO) during system configuration, or a 
logical node name associated with the X.25 Link communications driver 
(JODSX) during network configuration. This parameter indirectly specifies 
which communications interface you wish to use. 





For X.21, you can specify a node rather than a DS device. DS will first 
determine if a valid LDEV or device class name was given. If that is not 
the case, DS will search the configuration data base to determine if it isa 
node name. 


NOTE 


X.25 Link users should always specify a node name 
rather than a line identifier. The logical node name 
(mentioned in the dsdevice parameter description) 
appears in the configuration file, NETCON, for a Public 
Data Network (PDN). A Remote Node (RN) table entry 
relates the logical node name (specified in this command) 
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-DSLINE 


buffersize 


EXCLUSIVE 


COMP 


NOCOMP 


QUIET 


to the logical device number of the appropriate IODSX 
driver (the X.25 driver), and to the PDN address of the 
destination node. 


A decimal integer specifying the size (in words) of the DS/3000 line buffer 
to be used in conjunction with the communications line. The integer must 
be within the range 304 < buf fer-size < 4095 when used with the SSLC 
or HSI, or within the range 304 < buffer-size < 1024 when used with 
the INP. The default value is the buffer size entered in response to the 
PREFERRED BUFFER SIZE prompt during system configuration. This 
parameter overrides the MPE configured value when specified by the first 
user to open the given line. If you are using X.25, this parameter is ignored. 


This parameter, if present, specifies that you want exclusive use of the 
communications line. If the requested line or specified communications 
interface is already open and you have specified the EXCLUSIVE option, 
DS/3000 will deny you access to the line (you cannot open it). (See "Line 
Opening Failures" later in this section.) Opening an EXCLUSIVE line 
requires the user to have CS and ND capabilities. 


By using this parameter, you can override the current system default, which 
was set at configuration time (see Section 1! of the DS/3000 Network 
Administrator Manual) or set by the system operator (see Section 9), and 
activate data compression. In this way, the mode of operation is set for 
your subsequent DS activity. This parameter does not affect other users 
sharing the line. 


This parameter deactivates the data compression mode. 


When you issue the ;:DSLINE command with this parameter added, the 
message identifying the DS line number is suppressed. The messages 
associated with the subsequent REMOTE HELLO and REMOTE BYE commands 
will also be suppressed. 


The messages suppressed when the QUIET parameter is used may 
include information you would normally want to see or expect 
to see. For instance, if the remote account requires a password, 
and you do not include the password as part of the REMOTE 
HELLO command, the remote system’s prompt for that password 
will not be displayed. Since the REMOTE HELLO cannot finish 
until you supply that password, the terminal will appear to be 
"hung" when, in fact, it is only waiting for your response. 
Similarly, if the remote account has a logon UDC, any prompt 
produced by a command within that UDC will not appear. 
Again, until the unseen prompt 1s answered, the : REMOTE 
HELLO cannot complete, and the system will not respond with 
the appropriate remote or local system prompt (# or :). 








“ 


eo 





‘DSLINE 


The additional parameters that pertain only to opening a telephone line are as follows: 


telephonenumber 


Localidsequence 


remoteidsequence 


SELECT 


A telephone number consisting of digits, dashes, and special characters. The 
permitted special characters are: 


0 through 9 


/ (separator used for automatic call units that have a second dial tone 
detect) 


D (one-second delay. Used for European modems and automatic call units 
that require built-in delays) 


# (defined by the local telephone system) 
* (defined by the local telephone system) 


The maximum length permitted (including both digits and dashes) is 30 
characters. Provided that YES was entered in response to the DIAL 
FACILITY prompt during system configuration, this telephone number will 
be displayed at the operator’s console of your HP 3000 and the operator 
will then establish the telephone connection by dialing that number at the 
modem. (When the autodial feature is present in your system, the number 
provided here is dialed automatically.) The default telephone number is the 
one entered in response to the PHONE NUMBER prompt during system 
configuration. 


A string of ASCII characters contained within quotation marks. If you 
wish to use a quotation mark within an ASCII string, use two successive 
quotation marks. The maximum number of ASCII characters allowed in 
the string is 16. 


The supplied string of ASCII characters defines the ID sequence that will be 
sent from your HP 3000 to the remote HP 3000 when you attempt to 
establish the telephone connection. The default value is the ASCII string 
entered in response to the LOCAL ID SEQUENCE prompt during system 
configuration. 


Same format as Localidsequence. 


The supplied strings of ASCII characters define those remote HP 3000 ID 
sequences that will be considered valid during an attempt to establish the 
telephone connection. If the remote HP 3000 does not send a valid ID 
sequence, the telephone connection 1s terminated. The default set of 
remote ID sequences consists of the ASCII strings entered in response to the 
REMOTE ID SEQUENCE prompt during system configuration. 


The SELECT parameter is the equivalent of PHNUM for X.21 switched lines. 
The selecttonstgnalsequence, SELECT’s equivalent of a phone number, 
must be a string of | to 30 alphanumeric and/or special characters. 


JUL 87 
2219 


QUEUE 


NOQUEUE 


‘?DSLINE 


It must be delimited between two identical special characters. If the 
specified selectitonsignal sequence is less than 30 characters, it will be 
padded at the end with blanks. The selectitonsignalsequence can be 
given aS one or more blanks to indicate you wish to use the direct dial 
facility. (You must subscribe to it through your X.21 network.) The 
SELECT parameter value takes precedence over that specified in the 
configuration data base. 


This parameter allows your request to be queued when the X.21 network 
connection you wish to open is already in use. Your call will be connected 
as soon as the circuit is free. If another user is already queued, and you 
issue a :DSLINE command that allows queueing, a message will be printed 
telling you that you are queued behind a previous request. The default 
condition is NOQUEUE. 


This parameter deactivates queueing when you are opening an X.21 line. 
If the line is already in use when your : DSLINE 1s issued, your call request 
will not be completed when the ciruit becomes available. This is the 
default condition. 
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Opening a Line 


Dialing the Remote Computer 


When you are opening a telephone line, you may supply a telephone number as an optional parameter 
in the :DSLINE command to be dialed at the modem connected to the specified interface. If you 
supply a telephone number, DS/3000 displays a message on the system console telling the operator to 
dial that number. The operator, after dialing the specified number, enters YES or NO through the 
system console =REPLY command to let DS/3000 know whether or not the telephone connection was 
successfully made. If the operator enters YES, DS/3000 proceeds with the exchanging of ID sequences. 
If the operator enters NO, your : DSLINE request is denied (you cannot open the line). In either case, 
your terminal’s keyboard is disabled until the console operator responds. 


If you do not supply a telephone number, the sequence of events is as described in the above 
paragraph, except that DS/3000 uses (by default) the first telephone number 1 in the PHONELIST 
established during system configuration. 


If you do not supply a telephone number and no PHONELIST was established during system 
configuration, an I/O request message is displayed at the system console, but it does not include the 
number to be dialed. This method might be used when you will dial the remote HP 3000 yourself. 
Remember, however, that the console operator must still know whether you dialed successfully, since 
he must respond to the console message before you are granted access to the line. Because your 
terminal’s keyboard is disabled until the console operator responds with YES or NO, it is recommended 
that you always supply a telephone number in the :DSLINE command. 


ID Sequences 


Once a telephone connection to a remote HP 3000 exists, the two computers exchange ID sequences 
with one another. Within the context of DS/3000, an ID sequence is a string of up to 16 ASCII or 
EBCDIC characters, or octal or hexadecimal numbers, that identifies a particular computer. 


During system configuration, each HP 3000 can be assigned a local ID sequence and a list of remote 
ID sequences. The local ID sequence identifies the particular HP 3000 in which it is established; the 
remote ID sequences identify those remote computers with which a communications link can be 
established over the public telephone network. 


In the :DSLINE command, you can supply (as optional parameters) a local ID sequence and one or 
more remote ID sequences to be used instead of those established during system configuration. (See 
Figure 2-9.) 


When a telephone connection is established between your HP 3000 and a remote HP 3000, the local 
ID sequence supplied in your :DSLINE command is transmitted to the remote system. Then the 
remote system transmits its local ID sequence over the telephone line to your HP 3000. The received 
ID sequence is then compared against the remote ID sequence(s) supplied in your :DSLINE command. 
If that ID sequence is found to be valid, the telephone connection is considered successful and 
DS/3000 grants you access to the line. If the ID sequence received at either end of the line is not 
considered valid, your :DSLINE request is denied (you cannot open the line). 


If you do not supply any ID sequences, DS/3000 uses those established during system configuration. If 
no ID sequences were established during system configuration and you do not supply any, no local ID 
sequence is transmitted from your HP 3000 to the remote system and any remote ID sequence 
received is considered valid. 
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Opening a Line 


Muitiple Users 


Within a DS/3000 environment, it is possible for several users at either end of the line to share access 
to the same physical communications line or for a single user at one end of the line to obtain exclusive 
access to the line. 


As previously mentioned in the presentation of the :DSLINE command, the EXCLUSIVE parameter can 
be used to obtain exclusive access to the specified physical communications line. If you specify this 
parameter (and if access to the line is granted), no other user in either computer will be permitted to 
open that line until you close it. If you ask for exclusive access to a particular line and that line is 
already in use, DS/3000 denies your request (you cannot open the line). (See "Line Opening Failures" 
later in this section.) 


For hardwired lines and for dial-up lines, multiple users at either end of the line can specify the same 
physical line in :DSLINE commands and obtain access to that line as long as none of them requests 
exclusive access. In such a case, the users’ data is multiplexed, so that each user’s access to the line 
appears to be completely independent of all others. The exception for a telephone line is that all users, 
other than the one who originally opened the line, specify (explicitly or by default) the currently 
active remote ID sequence. Figures 2-7 through 2-11 present annotated examples, illustrating 
successful and unsuccessful attempts by different users to obtain access to the same line. 

















Opening a Line 
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Figure 2-7, Multiple User Example 1 





>HELLO USER.X :HELLO USER.Y 
:DSLINE REMOTE3 :DSLINE REMOTE3 
:REMOTE HELLO USER.X ;REMOTE HELLO USER.Y 


In this example, User X initiates a local session in System A, obtains access to the hardwired 
communications line that connects System A to System B, and initiates a remote session in System B. 
User Y subsequently initiates a local session in System A, obtains access to the same communications 
line, and initiates a remote session in System B. The request by User Y for the particular 


communications line is granted by DS/3000 because neither user asked for exclusive access to the 
line. 
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SYSTEM A 


SYSTEM B 
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Figure 2-8. Exclusive Option Example 


sHELLO USER.X sHELLO USER.Y 


:DSLINE REMOTE3 ;EXCLUSIVE :DSLINE REMOTE3 


sREMOTE HELLO USER.X 
In this example, User X initiates a local session in System A, obtains exclusive access to the 
hardwired communications line that connects System A to System B, and initiates a remote session in 


System B. User Y subsequently initiates a local session in System A and requests access to the same 


communications line. The request is denied by DS/3000 because User X already has exclusive access 
to the specified line. DS/3000 responds with: 


241 DS LINE IN USE EXCLUSIVELY OR BY ANOTHER SUBSYSTEM. (DSERR 241) 
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Configured Local ID: A | Configured Local ID: B 
Configured Remote IDs: B,C Configured Remote IDs: A,C 
SYSTEM A SYSTEM B 


REMOTE2 








Figure 2-9. Dial-up Line Multiple User Example 1 


:HELLO USER.X sHELLO USER.Y 
:DSLINE REMOTE2 & :DSLINE REMOTEe & 
; PHNUM=555-1234 & ; PHNUM=555-1234 & 
sREMID="B” *REMID="B° 
:REMOTE HELLO USER.X :REMOTE HELLO USER.Y 





In this example User X initiates a local session in System A and obtains access to the line identified 
by the device class name REMOTE2. The supplied telephone number is displayed at the system 
console of System A. The console operator establishes the telephone connection by dialing the 
number at the modem connected to the particular line and then enters YES through the system 
console to let DS/3000 know that the telephone connection was successfully made. The two 
computers exchange their configured local ID sequences. System A compares the received ID 
sequence (B) against the remote ID sequence specified by User X (REMID="B"). Since the received ID 
sequence 1s found to be valid, the telephone connection is allowed to remain in effect. User X then 
initiates a remote session in System B over the telephone line from his local log-on terminal. 


User Y subsequently initiates a local session in System A and requests access to the same line 
(REMOTE2). Since that line is already open, DS/3000 ignores the supplied telephone number (no 
message is displayed at the system console). Access to the currently opened line is granted to User Y 
because neither user requested exclusive access and User Y specified the currently active remote ID 
sequence (REMID="B") in the :DSLINE command. 
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Configured Local ID: A Configured Local ID: B 





Configured Remote IDs: B,C Configured Remote IDs: A,C 


SYSTEM A SYSTEM B 


REMOTE2 





Figure 2-10, Dial-up Line Multiple User Example 2 


HELLO USER. X HELLO USER.Y : 
:DSLINE REMOTE2 & :DSLINE REMOTE2 & 

» PHNUM=555-1234 & *PHNUM=555-2001 & 

*REMID="B" *REMID="C" 


:REMOTE HELLO USER.X 


In this example User X initiates a local session in System A and obtains access to the line identified ” 
by the device class name REMOTE2. The supplied telephone number is displayed at the system 

console of System A. The console operator establishes the telephone connection by dialing the 

number at the modem connected to the particular line and then enters YES through the system 

console to let DS/3000 know that the telephone connection was successfully made. The two 

computers exchange their configured local ID sequences. System A compares the received ID 

sequence (B) against the remote ID sequence specified by User X (REMID="B"). Since the received ID 

sequence is found to be valid, the telephone connection is allowed to remain in effect. User X then 

initiates a remote session in System B over the telephone line from his local log-on terminal. 


User Y subsequently initiates a local session in System A and requests access to the same line 
(REMOTE2). Since that line is already open, DS/3000 ignores the supplied telephone number, and no 
message is displayed at the system console. The request is denied by DS/3000 because the specified 
line is already open and User Y did not specify the currently active remote ID sequence (B) in his 
:DSLINE command. DS/3000 responds with: 


255 COMMUNICATIONS INTERFACE ERROR. UNANTICIPATED CONDITION. (DSERR 255) \ 
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Configured Local ID: (none) Configured Local ID: (none) 
Configured Remote IDs: (none) Configured Remote IDs: (none) 
SYSTEM A SYSTEM B 
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Figure 2-11. Dial-up Line Multiple User Example 3 


>HELLO USER.X :HELLO USER.Y 
:DSLINE REMOTE2 ;PHNUM=555-1234 :DSLINE REMOTE2 ;PHNUM=555- 1234 
:REMOTE HELLO USER.X :REMOTE HELLO USER.Y 


In this example User X initiates a local session in System A and obtains access to the line identified 
by the device class name REMOTE2. The supplied telephone number is displayed at the system 
console of System A. The console operator establishes the telephone connection by dialing the 
number at the modem connected to the particular line and then enters YES through the system 
console to let DS/3000 know that the telephone connection was successfully made. No ID sequences 
are exchanged because none were established (in either HP 3000) during system configuration and 
User X didn’t specify any in the :DSLINE command. User X then initiates a remote session in 
System B over the telephone line from his local log-on terminal. 





User Y subsequently initiates a local session in System A and requests access to the same line 
(REMOTE2). Since that line is already open, DS/3000 ignores the supplied telephone number (no 
message is displayed at the system console). Access to the currently opened line is granted to User Y 
because neither user requested exclusive access and User Y specified the currently active remote ID 
sequence (in this case none) in his :DSLINE command. 
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NOTE 


When no ID sequences are configured and the users don’t 
supply any in their :DSLINE commands, both are taking 
it on faith that they are connected to the proper remote 
computer. In this example, if User Y had specified 
PHNUM=555-2001, DS/3000 would have ignored this 
telephone number because the line is already open. User 
Y would have been connected to the currently active 
remote computer rather than the requested remote 
system. The total absence of configured or supplied ID 
sequences is safe only under very controlled 
circumstances. It is strongly recommended that all 
computers in a DS/3000 network that are capable of 
communicating over telephone lines have default local 
and remote ID sequences established during system 
configuration and that all line users specify the ID 
sequence of the desired remote computer (REMID=x) in 
their : DSLINE commands. 
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“REMOTE HELLO 


The REMOTE HELLO Command 


Once you have obtained access to a physical communications line using the :DSLINE command, you 
use the :REMOTE HELLO command to actually establish the communications link. The : REMOTE 
HELLO command initiates a remote session on your behalf in the HP 3000 connected to the other end 
of the communications line. 


The format of the :REMOTE HELLO command is presented here. Notice that, except for the two 
shaded items, it has exactly the same format as the standard MPE : HELLO command. 


Because the :REMOTE HELLO command 1s initiating a session for you in a remote HP 3000, the 
parameters in that command specify information which pertains to the operating environment of the 
remote HP 3000 instead of the local one. For instance, username, accountname, and groupname 
must all be valid as defined by the accounting structure of the remote HP3000, and the cpuseconds 
specified by the optional TIME parameter impose a time limit on the remote, rather than the local, 
session. 


SYNTAX 


:REMOTE HELLO [sessionname, ]username[/userpass] .acctname[/aectpass] 
[ ,groupname[/grouppass] ] 


[;TERM=termt ype] 
[; TIME=cpusecs] 
BS 

CS 


DS 
ES 


[;PRI= 


s INPRI=inputpriority 
;HIPRI 


[3;DSLINE=dsdevice] | 
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PARAMETERS 


sesstonname 


username 


userpass 


aectname 


acct pass 


groupname 


grouppass 


termt ype 


Arbitrary name used in conjunction with username and acctname 
parameters to form a session identity. Contains from | to 8 alphanumeric 
characters, beginning with a letter. Default is that no session name is 
assigned. 


A user name, established by the account manager, that allows you to log on 
under this account. Contains from 1 to 8 alphanumeric characters, 
beginning with a letter. 


(Required parameter.) 


User password, optionally assigned by the account manager. Contains from 
1 to 8 alphanumeric characters, beginning with a letter. 


Name of account, as established by the account manager. Contains from | 
to 8 alphanumeric characters, beginning with a letter. The aectname 
parameter must be preceded by a period. 


(Required parameter.) 


Account password, optionally assigned by the system manager. Contains 
from | to 8 alphanumeric characters, beginning with a letter. 


Name of the group to be used for local file domain and CPU time charges. 
Established by the account manager. Contains from | to 8 alphanumeric 
characters, beginning with a letter. Default is your home group, if you are 
assigned one by the account manager. 


(Optional if you have a home group; required if a home group has not been 
assigned.) 

Group password, optionally assigned by the account manager. Contains 
from | to 8 alphanumeric characters, beginning with a letter. 

(Required if assigned and you are logging on under other than your home 


group; optional if you are logging on under your home group.) 


Ignored. The TERM=termtype parameter of the HELLO command that 
initiated the local session also implicitly defines the log-on terminal type 
for any remote sessions initiated from the local session. 
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“REMOTE HELLO 


Maximum CPU time that the session can use, entered in seconds. When the 
limit is reached, the session is aborted. Must be a value from | to 32767. 
To specify no limit, enter a question mark (?) or UNLIM, or omit the 
parameter. Default is no limit. 


Execution priority class. BS is highest priority; ES is lowest. If you specify 
a priority that exceeds the highest permitted priority for your account or 
user name by the system, MPE assigns the highest priority possible below BS. 
Default is CS. 


NOTE 


DOS and ES are used primarily for batch jobs. Their use 
for sessions is discouraged. 


Relative input priority used in checking against access restrictions imposed 
by the jobfence, if one exists. Takes effect at log-on time. Must be a value 
from 1 (lowest priority) to 13 (highest priority). If a value is specified that 
is less than or equal to current jobfence set by the console operator, the 
session is denied access. Default is 8 or 13, depending upon the System 
Logging options in effect. 


Request for maximum session-selection input priority, causing the session to 
be scheduled regardless of current jobfence or execution limit for sessions. 
This parameter can be specified only by users with System Manager or 
System Supervisor capability. (If not, the system tries to log you on with 
INPRI=13.) Default is the current jobfence and execution limit. 


The device class name or logical device number assigned to the DS/3000 
communications driver (IODSO) during system configuration, or a logical 
node name associated with the X.25 Link communications driver (IODSX) 
during network configuration using NETCONF. This parameter, if present, 
specifies which line you wish to use. 


(Optional parameter if a line is already open; otherwise it is required.) 


NOTE 


X.25 Link users should always use a node name rather 
than a line identifier. 
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So far, we have been talking entirely about the :DSLINE and :REMOTE HELLO commands being used 
in conjunction with one another: the :DSLINE command obtaining access to a physical line and the 
sREMOTE HELLO command actually establishing the communications link by initiating a remote 
session over the acquired line. As you may have guessed from the above parameter definitions, the 
:DSLINE parameter of the ;:REMOTE HELLO command gives you a new, and simpler, way to obtain a 
line and establish a communications link. If you are satisfied to use the default DS/3000 line buffer 
size and you do not need exclusive use of the line, you can acquire a line and initiate a remote session 
over that line by using a single command: a : REMOTE HELLO command with the :DSLINE parameter. 
If you open a line in this way, however, it remains open only for the duration of the particular remote 
session (when the remote session is terminated the line is automatically closed). If, on the other hand, 
you use the :DSLINE command to open a line, the line remains open for the duration of the local 
session (or until you explicitly close the line). 


To illustrate this, look again at the example in Section 1. In that example, the :DSLINE command was 
used to obtain access to the hardwired line REMOTE! and the :REMOTE HELLO command was used to 
initiate a remote session over the line: 

:DSLINE REMOTE1 

DS LINE NUMBER = #L3 

sREMOTE HELLO RUSER.RACCOUNT 

HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 9:08 AM 


WELCOME TO SYSTEM B. 


NOTE 


In this case, the acquired line remains open when the 
remote session is terminated. 


By including the :DSLINE parameter in the : REMOTE HELLO command, essentially the same 
operations could be performed while using a single command, as follows: 


:REMOTE HELLO RUSER.RACCOUNT ;DSLINE=REMOTE1 
DS LINE NUMBER = #L3 


HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 9:08 AM 


WELCOME TO SYSTEM B. 


NOTE 


In this case, the acquired line is closed when the remote 
session is terminated. 


These same examples can be followed when you use a dial-up line. However, the telephone line will 
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work properly for you only under the following very limited circumstances: 


You must be satisfied to use the default DS/3000 line buffer size established during system 
configuration. 


The default ID sequences established in both computers during system configuration must 
properly identify both your local HP 3000 and the desired remote HP 3000 (or no ID sequences 
were established during system configuration in either computer). 


You must dial the remote computer yourself at the local system modem, or the line must be 
connected to, and configured for, autodialing. Note that if you cannot successfully make the 
telephone connection you cannot abort the :REMOTE HELLO command; the command will be 
rejected by DS/3000 if no connection is established within 15 minutes, unless another value was 
specified at configuration time. 


The likelihood of all of the above conditions existing for a particular use of DS/3000 is rather slim. 
In most DS/3000 environments you will want to explicitly define the ID sequence of the desired 
remote computer to guarantee that the proper connection is established, and you will want to provide 
a telephone number so that you can let DS/3000 know immediately if a telephone connection cannot 
be made. (It is not acceptable to tie up a communications interface and your log-on terminal waiting 
for an unsuccessful :DSLINE or :REMOTE HELLO request to be rejected.) 


Special consideration must be paid to the contents of any remote logon UDCs 
activated by a :REMOTE HELLO command. These UDCs are commonly constructed 
to execute a series of batch processes or initiate a turnkey application. In such 
cases, the command : BYE 1s often the final command in the sequence. The 
execution of this : BYE in a remote logon UDC will generate the following error 
messages: 


REMOTE HELLO Must Be Done To Initiate Remote 
Session. (DSERR 227) 
UNABLE TO COMPLETE THE REMOTE COMMAND. (CIERR 1316) 


These messages are generated because the :REMOTE HELLO does not actually 
complete until it finishes executing the commands within the UDC file. The final 

: BYE, however, terminates the remote session. So when the remote system replies to 
the :REMOTE HELLO, DS/3000 finds that no remote session has been established 
and returns an error. 


It is not safe to assume, however, that the error message has been generated solely 
because of the : BYE command in the remote logon UDC, since the same message 
will be generated if the :REMOTE HELLO fails for some other reason, or if the 
execution of a UDC fails on an internal error. When this error message appears, 
then, it may be difficult to interpret the actual cause of the error. Accordingly, it 
is recommended that the user avoid inserting the : BYE command in the remote 
account’s logon UDC, and find an alternative way of accomplishing the particular 
batch or application processing. One method would be to execute a job stream from 
within the local session. 
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Opening Multiple Lines 


Within your local session, you can open more than one physical communications line and you can have 
remote sessions active concurrently over all of the opened lines. However, when operating without 
X.25 Link, you are limited to one remote session per physical line at any given time. 


If access to the specified line is obtained, DS/3000 responds to each : DSLINE command by displaying 
a DS line number at your log-on terminal. This line number is roughly analogous to the file number 
returned by the MPE FOPEN intrinsic, in that it is an arbitrary number that uniquely identifies 
(within your local session) your current access to a particular communications line. It has no 
relationship to the logical device number or any other configuration parameter associated with the 
line. DS line numbers are meaningful only if you have more than one line open concurrently within a 
single local session. In that case, you are assigned a separate DS line number for each line you have 
opened, and you subsequently use these numbers to specify which line you wish to use for a given 
remote command (or sequence of remote commands) or to close a particular line without closing the 
others. 


Figure 2-12 illustrates a situation where a user has established two hardwired communications links 
concurrently from within a single local session. Take a closer look at that situation and examine the 
sequence of commands that was used to create it. 


SYSTEM A REMOTES SYSTEM 8 
/ (DS Une number 3) 





=. REMOTE! 


(DS Line number 4) 





User’s N 
Log-on * SYSTEM C 


Terminal XY 
‘N REMOTE 
— — \_SESSION 





Figure 2-12. Multiple Line Example (Hardwired Lines) 
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First the user sat down at a terminal connected to System A and initiated a local session: 
( sHELLO USER. ACCOUNT 
HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:37 PM 


WELCOME TO SYSTEM A. 


td 
e 


USER and ACCOUNT are valid user and account names, respectively, as defined by the accounting 
structure of System A. 


Now, we have the situation illustrated in Figure 2-13. Notice that, at this point, no communications 
link exists between any of the three systems. 


SYSTEM A REMOTES SYSTEM B 





REMOTE 1 





SYSTEM C 
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Figure 2-13, Initiating the Local Session 
(Hardwired Example) 


Opening a Line 
Next, the user acquired access to a line between Systems A and B and initiated a remote session in 
System B: 

sDSLINE REMOTE3 

DSLINE NUMBER = #L3 

sREMOTE HELLO RUSER.RACCOUNT 

HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:38 PM 

WELCOME TO SYSTEM B. 
REMOTES is the device class name (as defined within System A) associated with the particular line. 
RUSER and RACCOUNT are valid user and account names, respectively, as defined by the accounting 
structure of System B. 
Now we have the situation illustrated in Figure 2-14. 
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Figure 2-14, Establishing the Link With System B 
(Hardwired Example) 
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Finally, the user acquired access to a line between Systems A and C and initiated a remote session in 
System C: 


:DSLINE REMOTE1 
DS LINE NUMBER = #L4 
:REMOTE HELLO RUSER.RACCOUNT 


HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:39 PM 


WELCOME TO SYSTEM C 


° 


REMOTE1 is the device class name (as defined within System A) associated with the particular line. 
RUSER and RACCOUNT are valid user and account names, respectively, as defined by the accounting 
structure of System C. 


We end up with the situation illustrated in Figure 2-15, which is identical to Figure 2-12 that started 
this example. 
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Figure 2-15, Establishing the Link With System C 
(Hardwired Example) 
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Figure 2-16 illustrates a situation where a user has established two telephone communications links 
concurrently from within a single local session. Take a closer look at that situation and examine the 
sequence of commands that was used to create it. 
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Figure 2-16. Multiple Line Example (Telephone Lines) 
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First the user sat down at a terminal connected to System A and initiated a local session: 





>HELLO USER. ACCOUNT 
HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:37 PM 


WELCOME TO SYSTEM A. 


USER and ACCOUNT are valid user and account names, respectively, as defined by the accounting 
structure of System A. 


At this point, we have the situation illustrated in Figure 2-17. Notice that, so far, no communications 
link exists between any of the three systems. 
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Figure 2-17. Initiating the Local Session 
(Dial-up Example) 
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Next, the user acquired access to a telephone connection between Systems A and B and initiated a 
remote session in System B: 


:DSLINE REMOTE2 ;LOCID="A" ;REMID="B" ;PHNUM=555-8001 


DS LINE NUMBER = #L3 
:REMOTE HELLO RUSER.RACCOUNT 


HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:38 PM 


WELCOME TO SYSTEM B. 


° 


REMOTE2 is the device class name (as defined within System A) associated with the particular line, A 
and B are the ID sequences identifying Systems A and B, respectively, and 555-8001 is the telephone 
number of the modem connected to the communications interface at System B. RUSER and RACCOUNT 
are valid user and account names, respectively, as defined by the accounting structure of System B. 


Now we have the situation illustrated in Figure 2-18. 
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Figure 2-18. Establishing the Link With System B 
(Dial-up Example) 
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Finally, the user acquired access to a line between Systems A and C and initiated a remote session in 
System C: 


:DSLINE REMOTE3 ;LOCID="A" ;REMID="C"_;PHNUM=377-2000 
DS LINE NUMBER = #L4 


:REMOTE HELLO RUSER.RACCOUNT 
HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:39 PM 


WELCOME TO SYSTEM C. 


REMOTES is the device class name (as defined within System A) associated with the particular line, A 
and C are the ID sequences identifying Systems A and C, respectively, and 377-2000 is the telephone 
number of the modem connected to the communications interface at System C. RUSER and RACCOUNT 
are valid user and account names, respectively, as defined by the accounting structure of System C. 


We end up with the situation illustrated in Figure 2-19, which is identical to Figure 2-16 that started 
this example. 
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Figure 2-19. Establishing the Link With System C 
(Dial-up Example) 
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Opening a Line 


Figure 2-20 illustrates a situation where a user has established two X.25 communications links 
concurrently from within a single local session. Take a closer look at that situation and examine the 
sequence of commands that was used to create it. 
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Figure 2-20, Multiple Line Example (X.25 Lines) 


2-43 


Opening a Line 


First the user sat down at a terminal connected to System A and initiated a local session: 
sHELLO USER. ACCOUNT 
HP3000 / MPE V G.02.00. TUE, OCT 22, 1985, 1:37 PM 
WELCOME TO SYSTEM A. 
USER and ACCOUNT are valid user and account names, respectively, as defined by the accounting 
structure of System A. 


At this point, we have the situation illustrated in Figure 2-21. Notice that, so far, no communications 
link exists between any of the three systems. 
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Figure 2-21. Initiating the Local Session 
(X.25 Example) 
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Next, the user acquired access to an X.25 connection between Systems A and B and initiated a remote 
session in System B: 


:DSLINE NODEB 

DS LINE NUMBER = #L3 

:REMOTE HELLO RUSER.RACCOUNT 

HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:38 PM 


WELCOME TO SYSTEM B. 


NODEB is the nodename (as defined within System A) associated with the particular line. RUSER and 
RACCOUNT are valid user and account names, respectively, as defined by the accounting structure of 
System B. 


Now we have the situation illustrated in Figure 2-22. 
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Figure 2-22. Establishing the Link With System B 
(X.25 Example) 


Opening a Line 
Finally, the user acquired access to a line between Systems A and C and initiated a remote session in 
System C: 

:DSLINE NODEC 

ENVIRONMENT 2: REMOTES 

:REMOTE HELLO RUSER.RACCOUNT 

HP3000 / MPE V_ G.02.00. TUE, OCT 22, 1985, 1:39 PM 


WELCOME TO SYSTEM C. 


NODEC is the nodename (as defined within System A) associated with the particular line. RUSER and 
RACCOUNT are valid user and account names, respectively, as defined by the accounting structure of 
System C. 


We end up with the situation illustrated in Figure 2-23, which is identical to Figure 2-20 that started 
this example. 
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Figure 2-23, Establishing the Link With System C 
(X.25 Example) 
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Line Opening Failures 





There are several reasons why a :DSLINE command for opening a communications line might be 
rejected by DS/3000, some of which have been illustrated earlier in this section. 


The following list summarizes the likely causes of a line opening failure that are common to lines in 
general: 


e You made a syntax error in the :DSLINE command. 

e You gave an erroneous line or node name specification (dsdevice) in the :DSLINE command. 
(There is no IODSO entry in the system configuration with the specified device class name or 
logical device number, or the remote node name you specified was not defined in the network 
configuration database). 


e The line was not opened by the local console operator. 


e The line was not opened by the remote console operator. 





e The remote operator may have lowered the session LIMIT. 


© The local console operator may have used the SLAVE option to limit DS activity to incoming users 
only. 


e The remote console operator may have used the MASTER option to prohibit access to the system. 


e All virtual terminals on the remote system are already in use, which means there are no remote 
resources available for you to establish a remote session. 





e All virtual circuits are in use (X.25 only). 
e Someone has exclusive access to the specified line. 
e You asked for EXCLUSIVE access to a line that is in use. 


e DS/3000 detected a hardware problem (the communications interface board is not responding 
correctly). 
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The following list summarizes the additional causes of a line opening failure on a dial-up telephone 
line: 





e The operator was not able to make the requested telephone connection and entered NO through 
the system console in response to the dial request message. 


e The remote computer rejected your local ID sequence. 
e The remote computer did not send a valid ID sequence (the received ID sequence did not match 
any of the remote ID sequences that you specified or, if you didn’t specify any, did not match any 


of the configured remote ID sequences). 


e The specified line is already in use and the remote ID sequence you supplied did not match the 
one used by the currently connected remote HP 3000. | 


The various error numbers and messages that might appear as a result of line opening failures are 
included in the summary of error codes and messages in Appendix A. 
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Closing a Line 





Once you have opened one or more communications lines, you can close any or all of them by using a 
variation of the :DSLINE command. The line closing format of the :DSLINE command is presented 
here. 


SYNTAX 


dsdevice 
:DSLINE <dslineNumber sCLOSE 
@ 





PARAMETERS 
dsdevice The device class name, logical device number, or logical node name specified 
in the :DSLINE command that opened a particular line. 
dslineNumber The DS line number assigned to you by DS/3000 when the particular line 
was opened. When this parameter is used, it must appear in the format 
#Ln, where n is the line number (see "Examples" on the following page). , 
@ This parameter specifies that you wish to close all of the lines that you 
currently have open. 
sCLOSE This parameter specifies that you wish to close the specified line(s). 


If no line identifier (dsdevice, dslineNumber., or @) is specified, DS/3000 closes the line that you 


most recently opened. 
NOTE 


When the last node issues a :DSLINE CLOSE command, 
the message CS I/O ERROR will appear on the remote 
console. This is normal, and should be ignored. 
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Examples 


The following examples illustrate the variations of the :DSLINE command that can be used for closing 
one or more communications lines. 


:DSLINE REMOTE3 ;CLOSE 
This form closes the line that is identified by the device class name REMOTES. 


:DSLINE 55 ;CLOSE 
This form closes the line that 1s identified by the logical device number $5. 


:DSLINE @ ;CLOSE 
This form closes all the lines that you currently have open. 


:DSLINE #L3 ;CLOSE 
This form closes the line that is identified by #L3. 


:DSLINE ;CLOSE 
This form closes the line that you most recently opened. 


If you are sharing one or more physical communications lines with other users, the above forms of the 
: DSLINE command close the line(s) for your application only (the other user’s applications are not 
affected). 
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SECTION 


REMOTE SESSIONS 





A communications link exists after you have initiated a session in the remote HP 3000 under the 
username, accountname, and groupname specified in the :REMOTE HELLO command. You now have 
two distinct sessions in existence simultaneously from the same log-on terminal: a local session (in the 
HP 3000 to which you first logged on) and a remote session (in the HP 3000 at the other end of the 
communications line). 


Within the local session, you have access to all I/O devices and disc files in your local HP 3000 (subject 
to the usual MPE file security, of course). This isa normal MPE interactive session in every respect. 
You enter MPE commands and use the various language and utility subsystems exactly as you would if 
DS/3000 were not present. This local session is running under the username, accountname, and 
groupname specified in the :HELLO command that you used to first log on. All user capabilities and 
file access available to you within the local session are determined by those log-on parameters. 


Within the remote session, you have access to all I/O devices and disc files in the remote HP 3000 
(again, subject to the usual MPE file security). With the few minor exceptions described in the 
following pages, this is also a normal MPE interactive session. All MPE commands and subsystems are, 
however, executed in the remote HP 3000. The terminal output resulting from the executed 
commands and subsystems appears at your local log-on terminal. The remote session is running under 
the username, accountname, and groupname specified in the : REMOTE HELLO command that you used 
in establishing the communications link. All user capabilities and file access available to you within 
the remote session are determined by those log-on parameters. 


For the sake of clarity and as a learning aid, the remainder of this section will treat local and remote 
sessions as separate (and essentially unrelated) entities that use only those resources available in the 
particular HP 3000 in which they are running. Actually, it is possible to access the I/O devices and 
disc files of the remote HP 3000 computer from your local session, and it is also possible to access the 
I/O devices and disc files of the local HP 3000 from your remote session. This more advanced activity 
will be covered in Section 4, "Remote File Access." 


ISSUING REMOTE COMMANDS 


Remember that, in the previous sections, the following sequence of commands was used to establish the 
communications link: 


RETURN HELLO command 

:HELLO USER. ACCOUNT and log-on 
display for 

HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 9:05 AM local session. 


WELCOME TO SYSTEM A. 
:DSLINE REMOTE? 
DS LINE NUMBER = #L3 


Remote Sessions 


HELLO command 


:REMOTE HELLO RUSER.RACCOUNT and log-on am 
display for 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 9:06 AM remote session. 


WELCOME TO SYSTEM B. 


At this point, the remote session has been initiated, but you are currently in the local session (as 
signified by the colon prompt character). To execute a command in the remote session, use the 
following construct: 


sREMOTE [xxx] command 


where xxx is the DS line number returned by DS/3000 when the communications line was opened, 

and command is the desired MPE command in its normal format. (The DS line number is necessary 

only if you have more than one communications line open simultaneously; if it is omitted, then the 

line which you most recently opened is referenced by default). In the example in Section 1, this , 
construct was used to execute a LISTF command, as follows: a“ 


sREMOTE LISTF 
FILENAME 


DATA1 DATAS DATAG FILES SOURCE 1 


Because the prefix REMOTE was included, the LISTF command is executed in the remote session (the am 
implied account and group names are those established by the :REMOTE HELLO command that 
initiated the remote session). Although the LISTF command is executed in the remote HP 3000, the 

output generated by the command is displayed at your local log-on terminal. 


Notice, in the above example, that the DS line number associated with the particular communications 

line was not specified (3 in this example). This is because, if no line number is specified, DS/3000 uses 

(by default) the line most recently opened. Only one communications line is open from your local 

session; so DS/3000 uses that line by default. If you had opened a second line, you would need to tell 

DS/3000 in which remote computer the remote command is to be executed. To tell DS/3000, include AR 
the appropriate DS line number in the remote command, as follows: -_ 


sREMOTE 3 LISTF 
FILENAME 


DATA1 DATAS DATA6 FILE3 SOURCE 1 


The above construct only allows you to execute a single remote command. After the remote command 
has been executed, control returns to your local session (as signified by the colon prompt character). 


But suppose that you want to execute a whole series of remote commands. It would obviously be a 


nuisance to have to prefix each command with the word REMOTE. DS/3000 provides a convenient 
solution to this situation. To execute a series of commands in the remote session, use the following 


construct: - 
% 
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sREMOTE [xxx] 


where xxx is again the DS line number of the desired communications line (specifying in which 
remote HP 3000 you want to execute commands). DS/3000 then prompts you for each command by 
displaying a # in column | of your terminal ( in place of the standard MPE colon prompt). In the 
example in Section 1, this construct was used for entering two remote MPE commands, EDITOR and 
BYE. 


After reviewing the example in Section |, try another example that uses more than those two remote 
commands: 


> REMOTE 
#LISTF 





FILENAME 


DATA‘ DATAS DATAS6 FILES SOURCE 1 
#PURGE DATAS 

#PURGE DATAG6 

#LISTF 


FILENAME 


DATA1 FILE3 SOURCE 1 
#RUN FCOPY.PUB.SYS 


HP32212A.0.03 FILE COPIER 


>FROM=DATA1 ;TO=DATA2 ;NEW 
EOF FOUND IN FROMFILE AFTER RECORD 679 


680 RECORDS PROCESSED ### 0 ERRORS 
>EXIT 


END OF PROGRAM 
#LISTF 


FILENAME 


DATA1 DATA2 FILES SOURCE 1 
#BYE 


CPU=4. CONNECT=7. MON, OCT 28, 1985, 9:13AM 
#: 


Notice that except for the # prompt (in place of the standard colon prompt) this looks exactly like a 
normal MPE interactive session. All of the commands shown in the previous example are entered 
through the local log-on terminal, but the MPE and FCOPY commands are executed in the remote 
session within the remote HP 3000. After each remote MPE command was executed, however, control 
remained in the remote session (as signified by the # prompt character). When the remote session was 
terminated and the user typed a colon (:) in response to the # prompt following the log-off message, 
control was then returned to the local session (as signified by the colon prompt). 
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Using the Remote Subsystem from a Batch Job 


While in a batch job, you can establish a remote session by using the :DSLINE or :REMOTE HELLO 
command. 


The job to be streamed may be similar to the following: 


:JOB USER. ACCOUNT 
:DSLINE REMOTE2 
:REMOTE HELLO RUSER.RACCOUNT 
:REMOTE 

#FILE OUT;DEV=LP 
#BUILD WORK;DISC=50 
#RUN USERPROG 
#PURGE WORK 

#: 

sREMOTE BYE 
:DSLINE;CLOSE 

:EOJ 


NOTE 


The remote # prompt is optional. 


An important point to remember is that, once established, the remote session is interacting with the 
job in the same way as it would interact with a terminal. If the remote session detects an error, the 
error is printed to $STDLIST. If the error generates a user prompt, the next record in the job file is 
read as the response (in the same manner as waiting for a character or on a terminal). The 
record is then lost to the job. 


The Key 

Within a remote session, you can use to temporarily interrupt remote processing. When doing 
so, either you may return control to the MPE Command Interpreter of your local HP 3000, or you 
may temporarily suspend the remote subsystem that you are executing without returning control to 
the local HP 3000. This is determined by how you execute commands in the remote session. There are 
two ways to execute commands in a remote session: 


e __ By prefixing each command with the word REMOTE. 


e By entering the word REMOTE, which prompts you for each command. 


Prefixing Each Command with REMOTE. 


When you are conducting a remote session by prefixing each command with the word REMOTE, 
pressing returns control to the local Command Interpreter and you receive the colon (:) 
prompt. To continue remote processing at the point where it was interrupted, you merely enter 
REMOTE RESUME in response to the local MPE colon prompt. 
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As an example, assume that you are in the midst of using the text editor in a remote session when you 
decide to start a job stream executing concurrently in your local HP 3000. The sequence of commands 
would be similar to the following: 


:REMOTE EDITOR 


HP32201A.7.17 EDIT/3000 MON, OCT 28, 1985, 9:11 AM 
(C) HEWLETT-PACKARD CO. 1985 


/ADD 
1 DOE, JOHN 29 M CHI 
2 BLACK, PATRICIA 23 F SF 
3 SIMON, NEIL 43 M NY 
4 MACK, SHIRLEY 38 F DET 
5 
Local 7 ae pressed here. 
session 
prompt. 
:STREAM COBTEST1 Control is now 
#J19 in the local 
:REMOTE RESUME session. 
READ pending Control is now 
MICHAELS, WILLIAM 32 M CHI back in the 
6 O’ LEARY, TIMOTHY 49 M DET remote session. 
~t MARTIN, MARY 34 F LA 
8 MURIN, JOICE 42 F CHI 


Notice that when was pressed, the text editor in the remote HP 3000 was waiting for you to 
enter the text for line 5. interrupted the remote session and passed control to the MPE 
Command Interpreter of the local HP 3000 (as signified by the colon prompt). The STREAM command 
was issued within the local session, which caused the file COBTEST 1 to be executed in the local HP 
3000. Then, when the RESUME command was issued, control was passed back to the remote session at 
the point where it was interrupted (that is, the text editor in the remote HP 3000 is now waiting for 
you to enter the text for line 5). When the text for line 5 is entered, the remote session proceeds as 
though nothing had happened. 


Note that by the end of the example, the local job stream, the local session, and the remote session are 
all operational simultaneously. 
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Entering REMOTE. 


When you are interacting with the remote Command Interpreter by having entered the word REMOTE 
and you are receiving the remote prompt (#), pressing will temporarily suspend the subsystem 
you are executing and will return control to the remote Command Interpreter. To continue remote 
processing at the point where it was interrupted, you merely enter RESUME in response to the remote 
prompt. 


As an example, assume that you are in the midst of using the text editor in a remote session when you 
decide to start a job stream executing in your remote HP 3000. The sequence of commands would be 
similar to the example shown previously, but with a few minor differences, as follows: 


:REMOTE 
#EDITOR 





HP 32201A.7.17 EDIT/3000 MON, OCT 28, 1985, 9:20 AM 
(C) HEWLETT-PACKARD CO. 1985 


/aDD 
1 LEWIS, LEO 51 M SV 
2 LAGERGREN, FRED 25 M SJ 
3 DICKINSON, MARY 21 F SC 


4 LAGREGREN, LINDA 24 F SJ 


a 
BREAK pressed here. 


#STREAM APLTEST1 Control is 
#J20 still in the 
#RESUME remote session. 


READ pending 

MELLO, HENRY 44M SJ 
6 SOARES, JOE 59 M LA 
7 LAWRENCE, ALICE 44 F SJ 
8 LEWIS, BOB 29 M WASH 


Notice that when was pressed, the text editor in the remote HP 3000 was waiting for you to 
enter the text for line 5S. interrupted the remote session, but control remained in the remote 
HP 3000 (as signified by the remote # prompt). The STREAM command executed the file APLTEST 1 
within the remote HP 3000. Then, when the RESUME command was issued, control was passed back to 
the point where the text editor was interrupted (that is, the text editor is waiting for you to enter the 
text for line 5). When the text for line 5 is entered, the remote session proceeds as though nothing had 
happened. 


The Control Keys 


Within a remote session (CONTROL)H, (CONTROL)X, and (CONTROL)Y perform exactly the same functions as they 
do in a normal MPE interactive session. 


For example, if you are using FCOPY or the text editor in a remote session, you can use (CONTROL)Y to 


prematurely terminate an FCOPY or text editor operation. When the operation terminates, control is 
still in the particular subsystem within the remote session. _ 
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Similarly, you can use (CONTROLJH to delete the last character entered or (CONTROL)X to delete the line of 
text currently being entered. In both of these cases, after the deletion occurs, control remains in the 
remote session. 


ISSUING LOCAL COMMANDS 


Whenever the standard MPE colon prompt 1s displayed at your terminal, you are in the local session. 
Within the local session, you enter MPE commands in their normal format in response to the colon 
prompt. If you are in the midst of a remote session (that is, you used the command : REMOTE, and 
DS/3000 is issuing the # prompt character), you can return control to your local session by entering a 
colon, as follows: 


#: 


In response to the remote colon, control returns to the MPE Command Interpreter of your local HP 
3000 which then prompts you for local commands with the colon prompt character. Note that the 
remote colon does not terminate the remote session; you can resume processing in the remote session by 
again using either of the constructs described under "Issuing Remote Commands." 


TERMINATING A REMOTE SESSION 


You can terminate a remote session either from within the local session or from within the remote 
session itself. 


From the Local Session 


Whenever the standard MPE colon prompt is displayed at your terminal, you are in the local session. 
To terminate a remote session from within your local session, use the following command: 


:REMOTE [xxx] BYE 


where xxx 1s the DS line number associated with the communications line connecting the particular 
remote session to your local session. (The DS line number is necessary only if you have more than one 
communications line open simultaneously; if it is omitted then the line that you most recently opened 
is referenced by default.) 


For instance, in the example in Section |, either of the following sequences could have been used to 
terminate the remote session: 
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a 
sREMOTE BYE 


CPU=4. CONNECT=7. MON, OCT 28, 1985, 9:13 AM 


tke OR #44 


#: 
>REMOTE 3 BYE 


CPU=4. CONNECT=7. MON, OCT 28, 1985, 9:13 AM 


In both cases, the remote colon was used to return control from the remote session to the local session. 
In either case, the remote session is terminated. Remote sessions are also automatically terminated 
when the local session is terminated. 


If the communications line was opened using the DSLINE= parameter of the :REMOTE HELLO 
command, the line is automatically closed when the remote session terminates. To initiate another 
remote session over the same communications line, you must once again open the line (using either the 
:DSLINE command or the DSLINE= parameter of the :REMOTE HELLO command) and then issue 
another :REMOTE HELLO command. 


If the communications line was opened using the :DSLINE command, it is still open. To initiate a new 
remote session over the same communications line, merely issue another :REMOTE HELLO command 


(you do not need to issue another :DSLINE command because the communications line is still open). 
To close the communications line, use the constructs presented in Section 2. 


From the Remote Session 


Whenever the # prompt is displayed at your terminal, you are in the remote session. To terminate a 
remote session from within the remote session itself, use the following command: 


#BYE 


Note that you do not need to supply a DS line number in this case, because DS/3000 knows implicitly 
which remote session you wish to terminate (that is, the one in which the #BYE command is executed). 


Remember that this command was used to terminate the remote session in the example at the end of 
Section 1, as follows: 


#BYE 


CPU=4. CONNECT=7. MON, OCT 28, 1985, 9:15 AM 
# 


Notice that although the remote session is terminated, DS/3000 is still issuing the # prompt character. 
To return control to the local session, issue a colon (described earlier under “Issuing Local Commands’). 


If the communications line was opened using the :DSLINE command, it is still open. To initiate 
another remote session over the same communications line, merely issue an appropriate remote MPE 
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HELLO command. (You do not need to use the prefix REMOTE because DS/3000 is still waiting for you 
to enter a remote command; nor do you need to issue another DSLINE command because the 
communications line is still open.) To close the communications line, use the constructs presented in 
Section 2. 





If the communications line was opened using the DSLINE= parameter of the :REMOTE HELLO 
command, the line is automatically closed when the remote session terminates. To initiate another 
remote session over the same line, you must once again open the line (using the : DSLINE command or 
the DSLINE= parameter of a :REMOTE HELLO command) and then issue another :REMOTE HELLO 


command. 
NOTE 


Including a : BYE command in a remote logon UDC is not 
recommended. For a fuller explanation regarding the use of 
logon UDCs on a remote system, refer to the discussion of 
the :REMOTE HELLO command in Section 2, pages 2-29 to 
2-33. 








3-9 


Remote Sessions 
































SECTION 


In the preceding sections, you have seen how you can establish a communications link between two HP 
3000s and thereby use the computing power of the remote HP 3000. But through the use of the 
DS/3000 Remote File Access (RFA) capability, programs running in your local session can: 


REMOTE FILE ACCESS 





e Use any of the devices connected to the remote HP 3000 as though they were connected directly 
to your local HP 3000 


e Access any of the disc files of the remote HP 3000 (subject to the normal MPE file security, of 
course) as though they resided at your local HP 3000 site. 


Section 4 is divided into two main parts. The first part, "Interactive Access", describes how you can 
issue local MPE FILE commands that define devices and/or files residing at the remote HP 3000 site. 
The second part, "Programmatic Access", describes how you can use the standard set of MPE File 
System intrinsics within your local programs to access devices and/or files residing at the remote HP 
3000 site. 


INTERACTIVE ACCESS 


After a DS/3000 communications link has been established, you can issue local MPE FILE commands 
that define devices and/or files residing at the remote HP 3000 site. To make this possible, the DEV= 
parameter of the MPE :FILE command was expanded to include a DS line specification in addition to 
the usual device specification. To specify a file that resides across a DS line, the format of the DEV= 
parameter is as follows: 


;DEV=[dsdevice]# [device] 


where dsdevice is the device class name, logical device number, or node name that you used when 
establishing the particular communications link (this specifies the physical line connecting the two 
computers); and device is the device class name or logical device number of the desired remote device 
as established within the remote HP 3000. It defaults to DISC. (Refer to the MPE Commands 
Reference Manual for the complete syntax and all parameters.) 


NOTE 


When the :FILE command ts entered on a remote 
system to point back toa file on the local system, 
dsdevice is omitted. 


The dsdevice# parameter (within the DEV= parameter) is the only parameter of the MPE : FILE 
command that is unique to DS/3000. This one small item of syntax is enormously powerful. It means 
that from within your local session you can access any of the devices and/or disc files of a remote HP 
3000 as though they resided at your local HP 3000 site. Access to remote disc files is, of course, 
subject to the usual MPE file security. The user, account, and group names that you specified in the 
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:REMOTE HELLO command when establishing the communications link are the ones used by MPE in 
the remote HP 3000 for determining your file access capabilities. 





If device is omitted, the local system is used instead of the remote system. This is useful in cases 
where, for example, a program is located on a remote system, but the data it uses is located on the local 
system. See Example #5. | 


Following are five annotated examples illustrating remote device and file access from a local session. 
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Example #1: Remote Off-Line Listing 


Assume that you, using the Text Editor on your HP 3000, are to maintain an ASCII file containing 
both uppercase and lowercase characters, but that you don’t have an upper/lowercase line printer. 
Assume further that elsewhere in the same building there is another HP 3000 with an 
upper/lowercase line printer, that both HP 3000s have DS capability, and that they are connected to 
one another by an interconnecting cable and communications interfaces. You can access the remote 
line printer as follows. 


First, the console operators of both computer systems OPEN the line. (See Section 9.) Then, you log on 
to your HP 3000 and establish a communications link with the remote HP 3000. 


>HELLO USER. ACCOUNT 
:REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2@ 


where USER and ACCOUNT are valid user and account names (respectively) within the accounting 
structure of your local HP 3000, RUSER and RACCOUNT are valid user and account names (respectively) 
within the accounting structure of the remote HP 3000, and LINE@ is the device class name of the 
local IODSO entry (or the node name associated with the IODSX entry) for the line that you want to 
use. 


Next, issue a local MPE : FILE command that defines the desired line printer as a remote device. 
:FILE LIST; DEV=LINE2#SLOWLP 


where LIST ts the formal designator by which you will subsequently reference the line printer, LINE2 
is the device class name (or node name) you used when establishing the particular communications 
link, the # symbol tells the local file system that the next parameter references a device on the remote 
system, and SLOWLP is the device class name (as established within the remote HP 3000) of the 
upper/lowercase line printer. 


Then, invoke the Text Editor of your local HP 3000, specifying the remote line printer as the off-line 
listing device: 


sEDITOR #*LIST 


Thereafter, direct the Text Editor offline output to the remote upper/lowercase line printer as though 
it were connected directly to your local HP 3000. For example, you could print the content of the file 
TEXTFILE on the upper/lowercase line printer as follows: 


/TEXT TEXTFILE 
/LIST ALL,OFFLINE 


The entire command sequence is as follows (see Figure 4-1): 


>HELLO USER. ACCOUNT 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:51 PM 


WELCOME TO SYSTEM A. 
>REMOTE HELLO RUSER.RACCOUNT ; DSLINE=LINE2 


DS LINE NUMBER = #L3 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:52 PM 
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WELCOME TO SYSTEM B. 





sFILE LIST;DEV=LINE2#SLOWLP | 
sEDITOR #LIST "5 
HP32201A.7.17 EDIT/3000 MON, OCT 28, 1985, 12:53 PM 

(C) HEWLETT-PACKARD CO. 1985 

/TEXT TEXTFILE 

/LIST ALL,OFFLINE 

#u% OFF LINE LISTING BEGUN. ### 


SYSTEM A SYSTEM B 







LOCAL 
SESSION 


EDITOR 


Textfile 


Log-On 
Terminal 


Upper/Lower Case — X 
Line Printer | 
(SLOWLP) 


Figure 4-1. Remote Off-Line Listing Example 
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Example #2: Locally Sorting a Remote File 


Assume that there is a file named SOURCE residing on a disc connected to a remote HP 3000 and that 
SOURCE contains a list of clients sorted alphabetically by the clients’ names. Assume further that the 
remote HP 3000 and your local HP 3000 both have DS/3000 configured and that they are 
interconnected by a hardwired connection. You wish to access the remote file SOURCE from your local 
HP 3000, sort its content alphabetically by the names of the states in which the clients reside, and 
store the sorted version in a newly created disc file named SORTED on your local HP 3000. You can 
do that (without disturbing the original content of SOURCE) as follows. 


First, the console operators of both computer systems OPEN the line. (See Section 9.) Then, log on to 
your local HP 3000 and establish a communications link with the remote HP 3000. 


>HELLO USER. ACCOUNT 
:REMOTE HELLO RUSER.RACCOUNT ; DSLINE=LINE2 


where USER and ACCOUNT are valid user and account names (respectively) within the accounting 
structure of your local HP 3000, RUSER and RACCOUNT are valid user and account names (respectively) 
within the accounting structure of the remote HP 3000, and LINE@ is the device class name of the 
local IODSO entry (or the node name associated with the IODSX entry) for the line that you want to 
use. 


Next, issue a local MPE : BUILD command to create the local disc file SORTED that will receive the 
sorted output. 


:BUILD SORTED; DISC=250, 1 ,1;REC=-80,16,F ,ASCII 


Then, issue two local MPE : FILE commands: one that defines the remote disc file SOURCE as the sort 
input file and one that defines the local disc file SORTED as the sort output file. 


:FILE INPUT=SOURCE ;DEV=LINE2#DISC 
:FILE OUTPUT=SORTED 


Then, invoke the Sort program, specify the sort key, and initiate the actual sort. 
:RUN SORT.PUB.SYS 
>KEY 50,9 
>END 
Note that the sort 1s performed in your local HP 3000, using the remote disc file SOURCE as the sort 


input file; the output of the sort is stored in the local disc file SORTED; and the original content of 
SOURCE is not altered. 


The entire command sequence is as follows (see Figure 4-2): 


>HELLO USER. ACCOUNT 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:51 PM 


WELCOME TO SYSTEM A. 
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REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2 
DS LINE NUMBER = #L3 


HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:52 PM 





WELCOME TO SYSTEM B. 


: BUILD SORTED; DISC=250,1,1;REC=-80,16,F ,ASCII 
:FILE INPUT=SOURCE ; DEV=LINE2#DISC 


sFILE OUTPUT=SORTED 
:RUN SORT.PUB.SYS 
»>KEY 50,9 

>END 


STATISTICS 


NUMBER OF RECORDS = 221 

RECORD SIZE (IN BYTES) = 80 

NUMBER OF INTERMEDIATE PASSES = 0 : 
SPACE AVAILABLE (IN WORDS) = 13,346 a 
NUMBER OF COMPARES = 45 

NUMBER OF SCRATCHFILE I0’S = 10 

CPU TIME (MINUTES) = .01 

ELAPSED TIME (MINUTES) = .14 


END OF PROGRAM 
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SYSTEM A SYSTEM B 








Log-On 
Terminal 





SOURCE 


Figure 4-2. SORT Remote File Access Examrle 
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Example #3: FCOPYing to a remote system 


Suppose that you want to copy a disc file from your local HP 3000 to a remote HP 3000. Assume a 
hardwired connection and DS/3000 is configured. You can perform the file copy operation as follows. 


First, the console operators of both computer systems OPEN the line. (See Section 9.) Then, you log on 
to your local HP 3000 and establish a communications link with the remote HP 3000. 


sHELLO USER. ACCOUNT 
:REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2 


where USER and ACCOUNT are valid user and account names (respectively) within the accounting 
structure of your local HP 3000, RUSER and RACCOUNT are valid user and account names (respectively) 
within the accounting structure of the remote HP 3000, and LINE@ is the device class name of the 
local IODSO entry (or the node name associated with the IODSX entry) for the line that you want to 
use. 


Next, issue a local MPE : FILE command defining the destination file (REMFILE) as being a remote 
disc file. 


:FILE REMFILE;DEV=LINE2#DISC 
Then, invoke the File Copier and specify the file copy parameters. 


:RUN FCOPY.PUB.SYS 
>FROM=LOCF ILE; TO=*REMFILE;NEW 


A new disc file named REMFILE is created in the home group of the RACCOUNT account in the remote 
HP 3000 and the content of the local disc file LOCFILE is then copied over the communications line 
into REMFILE. 


The entire command sequence is as follows (see Figure 4-3): 


:HELLO USER. ACCOUNT 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:51 PM 


WELCOME TO SYSTEM A. 

:REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2 

DS LINE NUMBER = #L3 

HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:52 PM 
WELCOME TO SYSTEM B. 

:FILE REMFILE;DEV=LINE2#DISC 


:RUN FCOPY.PUB.SYS 
HP32212A.3.19 FILE COPIER (C) HEWLETT-PACKARD CO. 1984 
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>FROM=LOCF ILE; TO=*REMFILE; NEW 
EOF FOUND IN FROMFILE AFTER RECORD 2017 





2018 RECORDS PROCESSED ### Q ERRORS 


>EXIT 
END OF PROGRAM 


SYSTEM A SYSTEM B 














FCOPY 


LOCAL \ — 
SESSION 
| 


LOCFILE 





Log-On 
Terminal 


REMFILE 





Figure 4-3, FCOPY Remote File Access Example 
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Example #4: Locally Running Remote Programs 


Assume that there is a COBOL source file named SOURCE1 residing on a disc connected to a remote 
HP 3000 and that you want to compile, prepare, and execute that program on your local HP 3000. 
Assume further that the remote HP 3000 and your local HP 3000 both have DS/3000 configured and 
a hardwired interconnection. You can locally compile, prepare, and execute the remote source file as 
follows. 


First, the console operators of both computer systems OPEN the line. (See Section 9.) Then, log on to 
your HP 3000 and establish a communications link with the remote HP 3000. 


sHELLO USER.ACCOUNT 
>REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2 


where USER and ACCOUNT are valid user and account names (respectively) within the accounting 
structure of your local HP 3000, RUSER and RACCOUNT are valid user and account names (respectively) 
within the accounting structure of the remote HP 3000, and LINE@ is the device class name of the 
local IODSO entry (or the node name associated with the IODSX entry) for the line that you want to 
use. 
Next, issue a local MPE : FILE command defining the file SOURCE1 as being a remote disc file. 

sFILE SOURCE1 ;DEV=LINE2@#DISC 
where LINE2 is the node name or the device class name that you used when establishing the 
communications link and DISC is the device class name (as established within the remote HP 3000) of 


the disc on which SOURCE1 resides. 


Then, invoke the COBOL compiler and the Segmenter of your local HP 3000, specifying the remote 
disc file SOURCE1 as the inputfile. 


:COBOLGO *SOURCE1 


The content of the remote disc file SOURCE1 is compiled, prepared, and executed in your local HP 
3000. 


The entire command sequence is as follows (see Figure 4-4): 


:HELLO USER. ACCOUNT 
HP3000 / MPE V- G.02.00. MON, OCT 28, 1985, 12:51 PM 


:REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2@ 
DS LINE NUMBER = #L3 


HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:52 PM 


:FILE SOURCE1 ;DEV=LINE2#DISC 
:COBOLGO *SOURCE1 


PAGE 0001 HP32213C.02.12 (C) HEWLETT-PACKARD CO. 1983 


(SOURCE1 is now being compiled.) 
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DATA AREA IS %000341 WORDS. 
CPU TIME = 0:00:01. WALL TIME = 0:00:07. 
END COBOL/3000 COMPILATION. NO ERRORS. NO WARNINGS. 


END OF COMPILE 

(The compiled version of SOURCE1 is now being prepared by the MPE Segmenter.) 
END OF PREPARE 

(The compiled and prepared version of SOURCE1 is now being executed.) 


END OF PROGRAM 


NOTE 


Due to the amount of time and system resources 
required for COBOL activity, this example does not 
make efficient use of a DS line. The general rule is 
to do the COBOL compile, preparation, and run on 
the same system where the data resides. Sometimes 
this means copying the data files to another system 
before (or after) COBOL activity, rather than 
copying across the line during the COBOL activity. 
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SYSTEM A SYSTEM B 





Segmenter 
User Program 





Log-On 
Terminal 





SOURCEL 


Figure 4-4. COBOLGO Remote File Access Example 
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Example #5: Remote Programs and Local Data 

Assume that there is a COBOL source program named SOURCE1 residing on a disc connected toa 
remote HP 3000 and that you want to run that program using a data file named DATA! residing on 
your local system. Assume further that the remote HP 3000 and your local HP 3000 both have DS 
capability and a hardwired interconnection. You can do that as follows: 


First, log on to your HP 3000 and establish a communications link with the remote HP 3000. 


>HELLO USER. ACCOUNT 
:REMOTE HELLO RUSER.RACCOUNT ; DSLINE=LINE2 


where USER and ACCOUNT are valid user and account names (respectively) within the accounting 
structure of your local HP 3000, RUSER and RACCOUNT are valid user and account names (respectively) 
within the accounting structure of the remote HP 3000, and LINE@ is the device class name of the 
local IODSO entry (or the node name associated with the IODSX entry) for the line that you want to 
use. 

Next, issue a remote MPE :FILE command that defines the data file DATA1 as being a local disc file. 


>REMOTE 
#FILE SOURCE1 ;DEV=# 


If you prefer, the ;:F ILE command can be issued from your local session as follows: 


sREMOTE FILE DATA1;DEV=# 


where # indicates that the remote session should "go back" to the local session to find the data file. 
Then, invoke the COBOL compiler and the Segmenter of your remote HP 3000. 
#COBOLGO SOURCE1 
Or, if you prefer, you can run the job from your local session, as follows: 
:REMOTE COBOLGO SOURCE1 
The entire command sequence is as follows (see Figure 4-5): 


>HELLO USER. ACCOUNT 
HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:51 PM 


>REMOTE HELLO RUSER.RACCOUNT ;DSLINE=LINE2@ 
DS LINE NUMBER = #L3 


HP3000 / MPE V G.02.00. MON, OCT 28, 1985, 12:52 PM 
> REMOTE 

#FILE DATA1 ;DEV=# 

#COBOLGO SOURCE1 


PAGE 0001 HP32213C.02.12 (C) HEWLETT-PACKARD CO. 1983 
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(SOURCE1 is now being compiled.) 
DATA AREA IS %000341 WORDS. 
CPU TIME = 0:00:01. WALL TIME = 0:00:17. 
END COBOL/3000 COMPILATION. NO ERRORS. NO WARNINGS. 
END OF COMPILE 
(SOURCE1 is now being prepared by the MPE Segmenter.) 
END OF PREPARE 


(The compiled and prepared version of SOURCE1 is now being executed, and: is accessing DATA1 
for data.) 


END OF PROGRAM 


SYSTEM A SYSTEM B 





COBOL 


DATAL 





Log-On 
Terminal SOURCE! 


Figure 4-5. COBOL Remote File Access Example 
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NOTE 


Many aspects of system resources (for example, 
memory size, CPU load, type of CPU load, time 
quantums, etc.) affect how COBOL and remote data 
base access activities are conducted in a DS/3000 
environment. In general, it is more efficient to 
transfer data, USL, and SL files before or after (but 
not during) COBOL activity. 


PROGRAMMATIC ACCESS 


Once a DS/3000 communications link has been established between your HP 3000 and a remote HP 
3000, you can use the standard set of MPE File System intrinsics within your local programs to access 
devices and/or files residing at the remote HP 3000 site. To make this possible, the format of the byte 
array referenced by the device parameter of the MPE FOPEN intrinsic was expanded to include a DS 
line specification in addition to the usual device specification. The format of the device byte array is 
as follows: 


[dsdevice]# [device] 


where dsdevice is the device class name, logical device number, or node name that you used when 
establishing the particular communications link (this specifies the physical line connecting the two 
computers) and device is the device class name or logical device number of the desired remote device 
as established within the remote HP 3000. (For a complete presentation of all FOPEN intrinsic 
parameters, refer to the MPE Intrinsics Reference Manual.) 


NOTE 


When the :FILE command is entered on a remote 
system to point back to a file on the local system, 
dsdevice is omitted. 


The addition of dsdevice# to the format of the byte array referenced by the device parameter has 
enormously powerful implications. It means that programs executing in your local HP 3000 can easily 
access any of the devices and/or disc files of a remote HP 3000 as though they resided at your local 
HP 3000 site. Access to remote files is, of course, subject to the usual MPE file security. The user, 
account, and group names that you specified in the :REMOTE HELLO command when establishing the 
communications link are the ones used by MPE in the remote HP 3000 for determining your file 
access capabilities. 


On the following pages, an annotated example illustrates remote device and file access from a local 
program running within a local session. 


The Condition Codes for the various MPE File System intrinsics retain their normal meanings. Any 
communications line errors will return a CCL. In the event of an error, you can call the MPE FCHECK 
intrinsic to determine what happened. When using the MPE File System intrinsics for remote file 
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access, the Message Block B (File System) error codes apply to the remote file. You may also use the 
MPE PRINTFILEINFO intrinsic to display the status of a remote file. 
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The following program example tests RFA capabilities by writing to a remote file, reading the records 
back, then listing the contents of the remote file on the remote line printer. 


Example 
The following program illustrates how remote files can be accessed by using file system intrinsics. 


$CONTROL USLINIT,ADR,MAP, CODE 
BEGIN 
INTEGER 
A, 
I:=-1, 
RDISCNUM, 
RLPNUM; 


BYTE ARRAY RMTLP’FILNAM(0:3):="RLP “3 
BYTE ARRAY RLPDEV(0:11); 

BYTE ARRAY RMTDISC’FILNAM(0:5):="RDISC "; 
BYTE ARRAY MSG(0:71); 

BYTE ARRAY RDISCDEV(0: 11); 


LOGICAL ARRAY LMSG(#*)=MSG; 
INTRINSIC PRINT,READ,FOPEN ,FWRITEDIR,FREADDIR,FWRITE,FCLOSE; 
<< User enters remote disc device class name into RDISCDEV. >> 


MOVE MSG:="INPUT REMOTE DISC DEVICE CLASS NAME ”"; 
PRINT(MSG,-35,0); 

MOVE MSG:="IN THE FORM .. DSDEVICE#DISCDEV "; 
PRINT(MSG,-31,0); 

A: =READ(LMSG,~-12); 

MOVE RDISCDEV: =MSG, (A); 


<< User enters remote LP device class name into RLPDEV. >> 


MOVE MSG:="INPUT REMOTE LP DEVICE CLASS NAME "; 
PRINT (MSG,-33,0); 

MOVE MSG:="IN THE FORM .. DSDEVICE#LPDEV "; 
PRINT(MSG,-29,0); 

A:=READ(LMSG,-12); 

MOVE RLPDEV:=MSG, (A); 


<< Open remote disc file. >> 


MOVE MSG:="OPENING REMOTE DISC FILE "; 
PRINT(MSG,-24,0); 
RDISCNUM: =FOPEN (RMTDISC’FILNAM,4,%104, -80,RDISCDEV) ; 
IF <> THEN 
BEGIN 
MOVE MSG:="COULD NOT OPEN REMOTE DISC FILE "; 
PRINT(MSG,-31,0); 
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GO TO OUT; 
END; 


<< Initialize remote disc file. >> 


MOVE MSG:="WRITING TO REMOTE DISC FILE "; 
PRINT(MSG,-27,0); 

MOVE MSG:=" "; 

MOVE MSG(1):=MSG(0),(71); 


<< Write ten copies of MSG to remote disc file as a line check. >> 


WHILE (I:=I+1) <10 DO 
BEGIN 
MOVE MSG:="REMOTE FILE ACCESS TEST "; 
FWRITEDIR(RDISCNUM,LMSG,36,DOUBLE(I)); <<RECORD TO BE 
WRITTEN>> 
IF <> THEN 
BEGIN 
MOVE MSG:="ERROR WHEN WRITING TO REMOTE DISC "; 
PRINT (MSG,-33,0); 
GO TO OUT; 
END; 
END; 


<< Initialize LP file. >> 


MOVE MSG:="OPENING REMOTE LP FILE "; 
PRINT(MSG,-22,0); 
RLPNUM: =FOPEN(RMTLP’FILNAM,4,1,,RLPDEV); 
IF <> THEN 
BEGIN 
MOVE MSG:="COULD NOT OPEN REMOTE LP FILE "; 
PRINT (MSG,-29,0); 
END; 


<< Read 10 records from remote disc and write them to remote >> 
<< LP, one at a time. >> 


Ts==1% 
WHILE (I:=I+ 1) < 10 DO 
BEGIN 
FREADDIR (RDISCNUM,LMSG,36,DOUBLE(I)); 
IF <> THEN 
BEGIN 
MOVE MSG:="COULD NOT READ REMOTE DISC FILE "; 
PRINT (MSG,-31,0); 
END; 
FWRITE(RLPNUM,LMSG,36,0); 
IF <> THEN 
BEGIN 
MOVE MSG:="COULD NOT PRINT TO REMOTE LP FILE "; 
PRINT (MSG, -34,0); 
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END; 
END; 





OUT; 
END. 
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SECTION 


USING A REMOTE DATA BASE 





°B 





TurboIMAGE is HP’s data base management system. With DS/3000, you can use it to access data 


bases on other computer systems. 
NOTE 


All references to TurboIMAGE in this section apply equally to 
IMAGE/ 3000 if you are using either MPE IV or a version of 
MPE V prior to G.02.00. Also note that IMAGE/3000 and 
TurboJMAGE databases can access one another, but with some 
constraints. Please refer to the TurboIMAGE Reference Manual 
cited in the Preface of this manual. 





If you want to access a data base that resides on one HP 3000 computer system while operating a 
session on another HP 3000 computer system, you may do so provided both systems have DS/3000 
capability. You may use a data base on a remote HP 3000 either from a program that is running on 
the remote system or from a program running on your local HP 3000. The various ways to open a 
communications line and initiate a remote session are described in Sections | through 4. This section 
describes ways to access data bases programmatically with DS/3000. For example, you can establish a 
communications link and remote session and then run a remote program accessing a data base on the 
remote machine as illustrated in Figure 5-1. 





Local Terminal 


‘HELLO ... 
-DSLINE ... 
“REMOTE HELLO ... 


sREMOTE RUN PROGCX ... 





Local HP 3000 Remote HP 3000 
Program PROGX 


Data Bose DBX 





Figure 5-1, Using a Remote Program. 
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ACCESS THROUGH A LOCAL APPLICATION PROGRAM 





If you want to access a remote data base using a local application program, there are three methods 
you may choose from. In all cases, a local program accesses a remote data base and the data is passed 
across the communications line. 


Method 1: Establishing the Session Interactively 


To use the first method, you interactively establish a communications link and a remote session and 
enter a :FILE equation for each remote data base. The : FILE equation specifies which data base is to 
be access on which remote system and device. A local application program can now access a remote 
data base, as shown in Figure 5-2. 


Lecal Terminal 












‘HELLO ... 
‘DSUNE ... 

sREMOTE HELLO ... 

‘FILE DEX;DEV=SYSX#DISCA 
‘FILE DBY;DEV=SYSX@DISCA 
"RUN PROGX 


Local HP 3000 Remote HP 35000 





SYSX 





Program PROGX: 







Dato Base OBX 
and 

Data Bose OBY 
reside an DISCA 










Calls DBOPEN 
for DBX and 
DBY data base. 








Figure 5-2, Using Method 1. 
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Method 2: Using the Command Intrinsic 


The second method is very similar to the first, but you use the MPE command intrinsic within your 
application program to establish the communications link, remote session and remote data base access. 
In order to use this method in a COBOL, RPG, or BASIC application program, you must write a 
procedure in SPL or FORTRAN and call the procedure. 


To use this method, you must issue a : REMOTE HELLO command (either as part of the :DSLINE 
parameter, or by issuing the :OSLINE as a seperate command) and a :F ILE equation by calling the 
command intrinsic for each of these commands. The command intrinsic is explained in the MPE 
Intrinsics Reference Manual, and information about accessing remote files is given in Section 4. 
Figure 5-3 contains a diagram of Method 2. 


Local Terminal 
















‘HELLO... 
:RUN PROGX 


Local HP 3000 


Program PROGX: 
Remote 3000 






Contains calls to 

COMMAND "DSUNE SYSX" 

COMMAND “REMOTE HELLO..." 
COMMAND "FILE OBX;DEV=SYSX#DISCA" 


SYSX 









Dato Base DBX 
resides on DISCA 


(program code) 


COMMAND "REMOTE daline#BYE..." 
COMMAND “OSUNE dsline§;CLOSE..." 


Figure 5-3. Using Method 2 


If you want to access more than one remotely located data base with an application program, you must 
enter one : FILE equation for each remote data base. It is important to remember that a : REMOTE 
HELLO to the same remote computer should not be repeated within a process since the second request 
for a remote session would log off the first one. 


When the application program calls the DBCLOSE procedure, or is ready to terminate execution, it 
must programmatically issue :REMOTE BYE and :DSLINE commands for the communications line 
specified with the foregoing command intrinsic. (Note that the application must also close all other 
files and devices it opened on the remote system, not just the database files, before the :REMOTE BYE 
and :DSLINE ;CLOSE commands. 
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If you use this method, any change in the data base name, account or password information requires 
modification of the application program. Since the application program maintains logical control over 
the commands that are issued, it is responsible for checking all status words returned by the remote 
system. 
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Method 3: Using a Data Base-Access File 





The third method involves creating a special file which we shall call the data base-access file (DBA 
file). This file provides TurboIMAGE with the necessary information to establish a communications 
link and a remote session. It also specifies the remote data base or data base-access file name so that 
the necessary TurboIMAGE intrinsics can be executed on the remote computer. 


Loco! Terminal 


:HELLO USERA.ACCTA,GROUPA 
:RUN PROGX 





Locg! HP 3000 





Program PROGX: 


Calls Remote 3000 
DBOPEN with BASE orroy 
containing OBAFY, SYSX 
Data Bose—Access file 
named DBAFY contains: 


Dato Bose DBY 


resides on DISCA 
In account ACCTB 





Ree 1: FILE OBY;OEV=SYSX#DISCA 
Rec 2: OSLINE SYSX;... 
Rec 3: USERAACCTA.GROUPA=HELLO USERBACCTB... 





Figure 5-4, Using Method 3 
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NOTE 


With Method 3, which uses the data base-access file, 
only one data base can be accessed using each data 
base-access file per :DSLINE. For example, if two 
computers are linked through two :DSLINEs, you can 
open one data base on each line. However, a second 
sREMOTE HELLO on either :OSLINE terminates the 
previous :REMOTE HELLO for that particular line. For 
multiple remote data base access, Method | or Method 2 
is recomended. If the data base-access file is used, 
automatic :REMOTE BYE and :DSLINE ;CLOSE 
commands are issued on the communications line 
specified in the data base-access file when the 
application program terminates execution. Note that 
even though the :REMOTE BYE and DSLINE ;CLOSE -_ 
commands happen automatically, the application (PROGX 
in this example) program should provide for closing all 
remote file and remote devices that might be open 
before the application ends. 
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By using this approach, the data base administrator can set up a user-table that provides more control 
over the data base users, and thus, enhances data base security. To create the data base-access file, use 
the Editor (Edit/3000). First use the :SET LENGTH command to accommodate the largest record to 
be included in the data base-access file, up to a maximum of 128 characters. The content of this file 
should be created in the format shown below. 


SYNTAX 

Record | sFILE dbnamel[=dbname2]; DEV=dsdevice#[DISC] 

Record 2 :DSLINE dsdevice [;LINEBUF=buffer-size] [;LOCID=local-id-sequence] 
[;REMID=remote-id-sequence] [;PHNUM=telephone-number] [;EXCLUSIVE] 
[; QUIET] 

Record 3 Lusername.lacctname[,lgroupname]=HELLO rusername [/rupasw] 
racetname[/rapasw] [,rgroupname[/rgpasw] }[;TIME=cpusecs] 
[;PRI=priority] sHIPRI 

sINPRI=inputpriority 

Records 4 Same format as Record 3. Specifies other user.account , group identification. 

through n 

PARAMETERS 

dbname! is the name of the data base or the data base-access file on the remote 

system you want to access, or is the formal file designator used in the 
program if dbnamed is specified. 

dbname2 is the name of the data base or the data base-access file on the remote 

system you want to access. 

dsdevice is the device class name or logical device number assigned to the DS/3000 

communications driver (IODSO) during system configuration, or a logical 
node name associated with the X.25 Link communications device (IODSX) 
during network configuration using NETCONF. 

buffer-size is a decimal integer specifying the size (in words) of the DS/3000 line 


buffer to be used in conjunction with the communication line. The integer 
must be within the range 304 <buffer-size<4096. The default value is 
the buffer size entered in response to the PREFERRED BUFFER SIZE 
prompt during system configuration. 


Local-id-sequence is a string of ASCII characters contained within quotations marks. If you 
wish to use a quotation mark within an ASCII string, use two successive 
quotation marks. The maximum number of ASCII characters allowed in 
the string is 16. 
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remote-id-sequence 


telephone-number 


EXCLUSIVE 


QUIET 


Lusername 


Lacetname 


Lgroupname 


The supplied string of ASCII characters defines the ID sequence that will be 
sent from your HP 3000 to the remote HP 3000 when you attempt to 
establish the telephone connection. If the remote HP 3000 does not 
recognize the supplied ID sequence as a valid one, the telephone connection 
is terminated. The default value is the ASCII string entered in response to 
the LOCAL ID SEQUENCE prompt during system configuration. 


Same format as Local-id-sequence. 


The supplied string of ASCII characters defines those remote HP 3000 ID 
sequences that will be considered valid when you attempt to establish the 
telephone connection. If the remote HP 3000 does not send a valid ID 
sequence, the telephone connection is terminated. The default set of remote 
ID sequences consists of the ASCII strings entered in response to the REMOTE 
ID SEQUENCE prompt during system configuration. 


is a telephone number consisting of digits and dashes. The maximum length 
permitted (including both digits and dashes) is 30 characters. If YES was 
entered in response to the DIAL FACILITY prompt during system 
configuration, this telephone number will be displayed at the operator’s 
console of your HP 3000 and the operator will then establish the telephone 
connection by dialing that number at the modem. The default telephone 
number is the first one entered in response to the PHONE NUMBER prompt 
during system configuration. 


specifies that you want exclusive use of the particular communications line. 
If the specified HSI, SSLC or INP is already open and you have specified the 
exclusive option, DS/3000 will deny you access to the line (you cannot open 
it). Opening an EXCLUSIVE line requires the user to have CS capability. 
This capability may be granted by a system manager or account manager. 


specifies that the message identifying the DS line number will be 
suppressed. The messages associated with subsequent :REMOTE HELLO and 
:REMOTE BYE commands will also be suppressed. In this case, the terminal 
operator is totally unaware that remote processing is taking place. 


is a user name on the local HP 3000, as established by an account manager, 
that allows you to log on under this account. This name is unique within 
the account. It contains from | to 8 alphanumeric characters, beginning 
with a letter. An at sign (@) may be used to indicate the log on user name. 


is the name of your account on the local HP 3000 as established by a system 
manager. It contains 1 to 8 alphanumeric characters, beginning witha 
letter. An at sign (@) may be used to indicate the log on account. 


is the name of a file group to be used for the local file domain and central 
processor time charges, as established by an account manager. It contains 
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rusername 


raccetname 


rgroupname 


rupasw 


rapasw 


rgpasw 


TIME=cpusecs 


BS 
CS 
DS 
ES 


PRI= 


INPRI=tnputpriority 
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from 1 to 8 alphanumeric charcters, beginning with a letter. An at sign (@) 
may be used to indicate the log on group. 


is a user name on the remote HP 3000 that allows you to log on under the 
remote account. It follows the same rules as username. An at sign (@) 
may be used to indicate rusername as with Lususername. 


is the name of the log on account on the remote HP 3000. It follows the 
same rules as Lacctname. An at sign (@) may be used to indicate 
racctname is the same as Lacctname. 


is the name of the log on group on the remote HP 3000. It follows the same 
rules as Zgroupname. An at sign (@) may be used to indicate rgroupname 
is same as Lgroupname. 


is the password assigned to rusername. 
is the password assigned to racetname. 
is the password asigned to rgroupnaie. 


is the maximum central processor time that your remote session can use, 
entered in seconds. When this limit is reached, the remote session is aborted. 
It must be a value from 1 to 32767. To specify no limit, enter a question 
mark or omit this parameter. Default: No limit. 


is the execution priority class that the Command Intepreter uses for your 
remote session, and also the default priority for all programs executed 
within the remote session. BS is highest priority; ES is lowest. If you 
specify a priority that exceeds the highest that the system permits for 
racetname or rusername, MPE assigns the highest priority possible below 
BS. Default: CS. 


NOTE 


DS and ES are intended primarily for batch jobs; their 
use for sessions is generally discouraged. 


is the relative input priority used in checking against access restrictions 
imposed by the job fence, if one exists. It takes effect at log on time. It 
must be a value from 1 (lowest) to 13 (highest priority). If you supply a 
value less than or equal to the current job fence set by the console operator, 
the session is denied access. Default: 8 if logging of session/job initiation is 


5-9 


Using a Remote Data Base 


enabled, 13 otherwise. 


HIPRI is a request for maximum session-selection input priority, causing the 


remote session to be scheduled regardless of the current job fence or 
execution limit for sessions. 


NOTE 


You can specify this only if you have system manager or 
supervisor capability. (Optional parameter) 


Syntax Considerations 


The following syntax should be noted: 


No spaces are allowed around the periods in the optional file reference, or separating dsdevice 
and the # sign, in Record |. 


Passwords are not allowed with the local user, account, and group names. They are not neccessary 
since the local user passes the security password checks when logging on the local session. 


NOTE 


Remote logon parameters must define a valid logon 
known to the remote machine. For example, if a 
particular user name requires a password on the remote 
machine, the password parameter is not optional in the 
data base-access file and must be supplied in the : HELLO 
command. 
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USER IDENTIFICATION. 


Records 3 through n in a DBA file tell TurboIMAGE which user, account, and group names on the 
local computer may access which user, account, and group names on the remote computer. You may 
specify remote user identification for more than one local user by creating a record for each local 
user.account,group in the format of Record 3 shown above. An at sign (@) may be substituted for 
any user, account, or group name in the record. If an at sign is substituted for Lusername, 
Laectname, or lgroupname, the name is replaced with the corresponding name specified at log on 
time. 


When a local user runs a program that DBOPEN the DBA file, TurboIMAGE searches for a match 
between the local user, account and group names 1n the DBA file and the names the user entered when 
logging on to the local session. When a match is found, TurboIMAGE performs the : FILE and 
:DSLINE commands, and a :REMOTE HELLO using the corresponding rusername, racctname, 
rgroupname, and passwords if present. If an at sign is found, it is replaced with the corresponding 
name to the left of =HELLO. For example, if the record contains USERA. ACCTA, GROUPA=HELLO 
@.ACCTB,@ TurboIMAGE replaces the first at sign with USERA and the second with GROUPA. If an at 
sign is not found, no substitutions are made. In either case, the information to the right of =HELLO is 
used as the remote log on identification. 


EXAMPLE. The following syntax should be noted: 

Record | FILE STORE;DEV=DSL1#DISC 

Record 2 DSLINE DSL1 

Record 3 USERA.ACCTA,GROUPA=HELLO USERB.ACCTA,GROUPB 

Record 4 @.ACCTA,GROUPA=HELLO USERA.ACCTA,GROUPA 

Record 5 USERB.ACCTB,@=HELLO USERB.ACCTX ,@ 

End of file 

If a user logs on with the log on identification indicated in the first column below, TurboIMAGE will 


use the corresponding user.acct, group identification in the second column to establish 
communication with the remote system. 


Log~on Identification Remote Identification Used 
User! USERA.ACCTA,GROUPA USERB.ACCTA,GROUPB 
User2 USERB.ACCTA,GROUPA USERA.ACCTA,GROUPA 
User3 USERB.ACCTB,GROUPB USERB.ACCTX,GROUPB 
User4 USERA.ACCTB,GROUPB None, no match found. 


The first user’s log-on identification matches the local user, account, and group names specified in 
Record 3, so the remote names specified in that record are used. The second user’s account matches 
Record 3 but the user name does not, so TurboIMAGE looks for another table entry with account 
ACCTA. Since the entry in Record 4 specifies any user (@) of ACCTA if their group is GROUPA, the 
second user’s remote identification will be that specified in Record 4. 


The third user logs on to ACCTB and a match is found in Record 5, since it specifies the same user 
name and accepts any group in the account. 
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The fourth user’s account matches Record 5 but the user name does not match. Therefore, the fourth 
user cannot access the remote data base with this application program. 


FILENAME. 

After you have created the file with the Editor, you should KEEP it UNNumbered. The file name must 
follow the same rules as a data base name. It must be an alphanumeric string from | to 6 characters, 
the first character must be alphabetic. 

ACTIVATING A DATA BASE-ACCESS FILE. 

After you have constructed a data base-access file, you must use the DBUTIL utility program to 
activate the file. The complete syntax for running the utility program is given in the TurboI MAGE 


Reference Manual. Here is a summary of the operating instructions: 


:RUN DBUTIL.PUB.SYS 


>»ACTIVATE data base-access file name 


Verification follows: 
FILE command: <resul t> 
DSLINE command: <result> 
HELLO command: <resul t> 
ACTIVATED 
> >EXIT 
DBUTIL verifies that the file to be activated: 
has a file code of zero 
is an UNNUMBERED, ASCII file 


has a record length <=128 characters 
has at least three records. 


If any of these conditions is not satisfied, activation fails. If all of the above are satisfied, DBUTIL 
prints the following message: 


Verification Follows: 
Then the utility program verifies the syntax of: 
e Record 1 
e Record 2 through dsdevice, which must be identical to the dsdevice specified in Record | 
e Records 3 through vn, through the parameter rgpasuw. 
This means that for Records 2 through ” only the positional parameters (those whose function 1s 


determined by their relative position within the command) are verified by DBUTIL. The remaining 
key word parameters are checked by the command interpreter at DBOPEN time. 
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If all of the above conditions are met, DBUTIL successfully activates the data base-access file, by 
changing the file code to the TurboJIMAGE reserved code -402. The example in Figure 5-5 illustrates 
how to create and activate a data base-access file. In this case, the file named DSASTR is to be used to 
gain access to the STORE data base residing on a remote system in the PAYACCT account. The remote 
system is referenced by dsdevice name MY. 





After the data base-access file is created using the Editor, it is enabled by using the DBUTIL utility 
program. 
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HELLO MEMBER1.PAYACCT Log on to the local 
- system. 
sEDITOR Run the Editor. 


HP32201A.07.17 EDIT/3000 THU, OCT 3, 1985 2:37 PM 
(C) HEWLETT-PACKARD CO. 1985 


/A Create records in data 
1 FILE STORE ;DEV=MY# base-access file. 
2 DSLINE MY 
3 MEMBER1.PAYACCT=HELLO MEMBER1.PAYACCT 
4 MEMBER2.PAYACCT=HELLO @.PAYACCT 
5 
/K DBASTR,UNN Keep the file. 
zs 
END OF SUBSYSTEM 
sRUN DBUTIL.PUB.SYS Run DBUTIL to enable 
>>ACTIVATE DBASTR file. 
Verification follows: 
FILE command: Looks good 


DSLINE command: Looks good 
HELLO command: Looks good 
HELLO command: Looks good 
ACTIVATED 
> >EXIT 


END OF PROGRAM 


Figure 5-5, Preparing a Data Base~Access File. 


ACCESSING DATA BASES. 


To reference the data base from your local application program, use the data base-access file name 
instead of the root file name when calling the TurboIMAGE procedure. The word array specified as 
the base parameter must contain a pair of blanks followed by the left-justified data base-access file 
name and terminated by a semicolon or blank. TurboIMAGE recognizes the -402 file code and 
establishes a communications link to the remote HP 3000. If the data base is succesfully opened, 
TurboIMAGE replaces the pair of blanks with the extra data segment number of the assigned Remote 
Data Base Control Block. The base parameter must remain unchanged for the remainder of the 
process. When the application program calls the DBCLOSE procedure or terminates execution, 
automatic :REMOTE BYE and :DSLINE commands are issued to terminate the session and close the 
communications line. 
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Figure 5-6 illustrates use of the data base-access file through a program named APPLICAN. After 
logging on to the local system, the user runs the program named APPLICAN from the local session. The 
base array in this program contains" DBASTR". When a call to DBOPEN 1s executed, TurboIMAGE 
establishes a communication line and remote session. When the program closes the data base, 
TurboIMAGE closes the line and terminates the remote session. 


sHELLO MEMBER2. PAYACCT Log on to local 
. system. 

sRUN APPLICAN Execute application 
program. 

DS LINE NUMBER = #L4 

HP3000 IIB. MON, OCT 28, 1985, 1:56 PM TurboIMAGE establishes 
a communications line 

WELCOME TO SYSTEM B. and remote session. 

CPU=2. CONNECT=1. MON, OCT 28, 1985, 1:59 PM When the data base is 

1 DS LINE WAS CLOSED closed, Turbo IMAGE 
closes the line and 

> BYE terminates remote 

~: session. 


Log off local system. 


Figure 5-6. Using a Data Base~Access File. 


QUERY/ 3000 


When you run QUERY/ 3000, which is accessed with RUN QUERY.PUB.SYS, you can specify the data 
base to be used in two ways. You can use the DEFINE command, which then prompts you for: 


DATA-BASE, 

PASSWORD, 

MODE (see Table 5-1 for available modes), 

DATA-SETS to be accessed, 

PROC-FILE, which stores FIND, REPORT, and UPDATE commands as procedures, 
OUTPUT, which specifies the output device. 


You can also specify these options individually, as QUERY/3000 commands. 


The DATA BASE= prompt can be answered with a remote data base name or the data base-access file 
name. Note, however, that perfomance can be significantly improved if you run QUERY/3000 in 
remote session, thereby accessing the data base on the system where it resides, rather than running 
QUERY/ 3000 locally to access a remote data base. 
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Table 5-1, Modes of Access 


find (read), replace, add, and delete entfies. 
(QUER Y/3000 requests TurboIMAGE to 
lock and unlock the data base dynamically 
when accessing it.) 


find and replace entries. 


find, replace, add, and replace entries. 


find entries. (QUERY/3000 locks and 
unlocks.) 


find entries. 





These modes give you exclusive access to the data base. All other modes allow others to share the 
data base. Search and sort items cannot be replaced. 




















SECTION 





PROGRAM-TO-PROGRAM 
COMMUNICATIONS | 6 | 


In the preceding sections, you have seen how you can establish communications links between several 
HP 3000 computers to form a telecommunications network and how you can execute programs in any 
of the HP 3000s from a single log-on terminal. Furthermore, you have seen that programs running 
within any HP 3000 in the network can, under the proper circumstances, obtain access to any of the 
hardware or software resources available throughout the network. At this point, you already have a 
powerful telecommunications network capability at your disposal. 


But for many teleprocessing applications, it is essential that separate user programs be able to be run 
simultaneously in separate computers within the network and that they be able to communicate 
efficiently with one another. 


Two capabilities answer that need: DS/3000 Program-to-Program (PTOP) Communications (described 
in this section) and MPE Interprocess Communications (IPC) (described in Section 8). 


You might ask, "Why can’t the normal process-handling capabilities of MPE be used for this purpose?” 
As you probably recall, the process-handling capabilities of MPE permit a user process (referred to as 
the "father" process), to create and activate one or more "son" processes that then run concurrently 
with the father process. Father and son processes can communicate efficiently with one another 
through the use of the SENDMAIL intrinsics, shared extra data segments, or a shared user file. 
Unfortunately, however, the process-handling capabilities of MPE were designed for use within a 
single processor. They cannot handle the intervention of a communications line between father and 
son processes. 


Suppose you were to log on to an HP 3000, gain access to a DS line, and initiate a remote session. 
Within the local session, you use a STREAM command to initiate the execution of a program named 
PROGA; and within the remote session, you use a STREAM command to initiate execution of a program 
named PROGB. You now have two programs executing simultaneously: PROGA in your local HP 
3000 and PROGB in the remote HP 3000. 


At this point, the two programs are entirely independent of one another: neither knows the other 
exists. If you add a shared access disc file to the situation, PROGA and PROGB can now read from 
and write to that file, and thereby communicate indirectly with one another. This arrangement works 
well as long as the data being deposited in the shared file does not have to be retrieved, processed, and 
responded to within a finite period of time. 


There are teleprocessing applications where this type of arrangement is not only adequate but makes a 
great deal of sense. For example, consider the case where a branch office is accumulating information 
that must be merged once a day into a data base residing at the main office. In this case, the two 
programs can make very effective use of the message file approach that IPC uses (see Section 8 fora 
description). 


As soon as an application tries to be truly interactive, however, this arrangement falters because the 
two programs cannot communicate directly. Each must know whether or not the other program is 
trying to transmit data. The more dependent each program is upon receiving data from the other, the 
more likely it is that PTOP should be used for the application. 


With the remote file access method of program-to-program communication (IPC), the two programs 


have no way of knowing if the other program is actually executing. With the POPEN intrinsic, the 
master program knows that the slave program is executing, because it created and activated the slave 
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PTOP Communications 


program’s process. Likewise, the slave program knows that the master program is executing, because | 
without an active corresponding master program, the slave itself would not be executing. -—,) 


The DS/3000 program-to-program communications facility provides nine intrinsics that make it 
possible for two or more user programs residing in separate HP 3000s to exchange data and control 
information directly (and efficiently) over DS/3000 communications links. 


The nature of any two programs that are communicating with one another in this manner is not 
symmetrical. One of them (referred to as the "master" program) is always in control and is the one 
that initiates all activity between the two programs. The other (referred to as a "slave" program) 
always responds to requests received from the master. Those intrinsics used within a master program 
are summarized in Table 6-1, and those used within a slave program are summarized in Table 6-2. 


Table 6-1. Master Program-to-Program Intrinsics, 





Initiates and activates a slave process in a remote HP 3000 and initiates 
program-to-program communication with the slave program. 


Sends a read request to the remote slave program asking the slave to send 
a block of data back to the master. 


PWRITE Sends a block of data to the remote slave program. 





PCONTROL Transmits a tag field (containing user-defined control information) to the 
remote slave program and receives a tag field back from the slave. 

PCLOSE Terminates (kills) the remote slave program’s process. 

PCHECK Returns an integer code specifying the completion status of the most 
recently executed master program-to-program intrinsic. 
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Table 6-2. Slave Program~to-Program Intrinsics. 


Receives the next request f rom the remote master program. 
ACCEPT Accepts (and completes) the request received by the preceding GET 
intrinsic call. 





REJECT Rejects the request received by the preceding GET intrinsic call. 
PCHECK Returns an integer code specifying the completion status of the most 
recently executed slave program-to-program intrinsic. 


Conceptually, the DS/3000 program-to-program intrinsics are very similar to the MPE process 
handling and file system intrinsics that are used for process-to-process communication within a 
single-system environment. Table 6-3 compares the intrinsics used for process-to-process 
communication within a single-system environment to those used for program-to-program 
communication within a distributed systems environment. 
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Initiate 
another 
process. 


Communicate 
with the other 
process. 


Terminate the 
other process. 


CREATE 
ACTIVATE 


Mail Intrinsics: 


SENDMAIL 
RECEIVEMAIL 


User Managed Extra Data Segment 


GETDSEG 
DMOVEIN 
DMOVEOUT 


Shared User File: 


FOPEN 
FREAD 
FWRITE 
FCONTROL 
FCLOSE 
FCHECK 


Father: 
KILL (a son) 


TERMINATE (self 
and all sons) 
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Table 6-3. Single System / Distributed Systems Comparison. 


Single System Distributed Systems 
(Process Handling) (Program~to-Program) 


Master (father) Requests: 


PREAD 
PWRITE 
PCONTROL 
PCHECK 


Slave (son) Responses: 
GET 
ACCEPT 


REJECT 
PCHECK 


Master (father): 
PCLOSE (a slave) 


TERMINATE (self 
and all slaves) 





























PTOP Communications 


When a DS/3000 communications link exists between two HP 3000s, a user program (the master 
program) can create and activate a son process (a slave program) in the remote HP 3000. The POPEN 
intrinsic performs this function, in place of the standard MPE CREATE and ACTIVATE intrinsics. 


After the master and slave programs are both executing, the master program can: 
e Send data (PWRITE) or control information (PCONTROL) directly to the slave program 


e Send a read request (PREAD) or control request (PCONTROL) to the slave program asking that the 
slave send data or control information back to the master 


e Check status (PCHECK) and terminate (PCLOSE) a slave program. 


Notice the striking similarity between this method of communication and the use of the MPE File 
System intrinsics FREAD and FWRITE. It is as though the master program is reading from or writing to 
a file -- a very intelligent file that is capable of making decisions, controlling input/output devices, 
and performing productive processing. 


PTOP INTRINSICS 


The following pages contain detailed descriptions of the PTOP intrinsics that were summarized in 
Tables 6-1 and 6-2. For convenience in locating specific items of information in this reference 
section, these detailed descriptions are presented in a format consistant with that used in the MPE 
Intrinsics Reference Manual. Also, since this part of the section will be used for repeated reference, 
the intrinsics are arranged in alphabetical sequence, rather than in the order of normal usage as they 
were presented in the summary tables. 


These PTOP intrinsics are callable from SPL, FORTRAN, Pascal, or COBOL II. To call a DS/3000 
PTOP intrinsic from a program, use the following procedure: 


1. Refer to the intrinsic description to determine the parameter types and their positions in 
the parameter list. 


2. Declare the variables or array names to be passed as parameters by type at the beginning of 
the program. 


3. Include the name of the PTOP intrinsic in an INTRINSIC declaration statement, or the 
language’s equivalent. 


4. Issue the intrinsic call at the appropriate place in your program. | 
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ACCEPT 


(Slave callable) Accepts (and completes) the requests received by the 
preceding GET intrinsic call and returns an optional tag 
field to the remote master program. 





SYNTAX 





PARAMETERS 
ttag integer array 
A twenty-word array used for transmitting a tag field. The format of the “ea 
tag field is defined by the user’s master and slave programs. a 
target integer array 
An array used for transmitting or receiving blocks of data. 


For PREAD requests, this array contains the block of data to be transmitted 
to the master program. 


For PWRITE requests, this array receives the block of data from the 
DS/3000 buffer. 


For POPEN and PCONTROL requests, this parameter has no meaning and 
should be omitted. 


teount integer by value 


An integer specifying the number of words (if positive) or bytes (if negative) “- 
to be transmitted or received. 


For PREAD requests, this parameter specifies how much data is to be 
transmitted from target to the master program. 


For PWRITE requests, this parameter specifies how much data is to be 
moved from the DS/3000 buffer to target. 


For POPEN and PCONTROL requests, this parameter has no meaning and 
should be omitted. 
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ACCEPT Intrinsic 


CONDITION CODES 


CCE Request completed successfully. 

CCG (Not returned.) 

CCL An error occured. Issue a PCHECK intrinsic call to determine what 
happened. 

OPERATION 


The ACCEPT intrinsic accepts the request received by the most recent GET intrinsic call, completes the 
requested operation, and transmits an optional tag field back to the remote master program. 


In the case of a POPEN request, the ACCEPT call transmits an optional tag field (t tag) to the remote 
master program. 


In the case of a PREAD request, the ACCEPT call transmits the specified number of words or bytes 
(teount) from target to the master program and transmits an optional tag field (1 tag) to the master 
program. 


In the case of a PWRITE request, the ACCEPT call moves the specified number of words or bytes 
(tcount) from the DS/3000 buffer to target and transmits an optional tag field (i tag) to the 
master program. 


In the case of a PCONTROL request, the ACCEPT call transmits an optional tag field (7 tag) to the 
remote master program. 


GET 


(Slave callable) Receives the next request from the remote master 
program. 





SYNTAX 


| Lonumber] ); 





FUNCTIONAL RETURN 


tfun integer 
0 An error occured. This value is returned only when the condition code CCL 
is also returned. Issue a PCHECK intrinsic call (with a dsnum parameter of 
zero) to determine what happened. } 
l POPEN request received. 
2 PREAD request received. 
3 PWRITE request received. ‘) 
4 PCONTROL request received. 
5 This value is returned only when the condition code CCG is also returned. 


It indicates that a pending MPE File System I/O without wait request was 
completed (instead of the expected remote DS/3000 I/O request). 
zonumber contains the file number associated with the completed I/O 





request. 

PARAMETERS 

ttag integer array 
A twenty-word array used for receiving a tag field. The format of the tag 
field is defined by the master and slave programs. 

il integer 


A word that has meaning only when a PREAD or PWRITE request is received 
from the master program. 
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tonumber 


GET Intrinsic 


For a PREAD request, 22 contains an integer specifying the number of words 
or bytes requested by the master program. 


For a PWRITE request, 272 contains an integer specifying the number of 
words or bytes transmitted from the master program to the DS/3000 
buffer on the remote system. 

integer 

A word that has meaning only when the condition code CCG and an zfun 
of 5 are returned. In that case, tonumber contains the MPE File System 


file number associated with the completed I/O without wait request. 


Default: No file number is returned. 


CONDITION CODES 


CCE 


CCG 


CCL 


OPERATION 


Request received successfully. 


The implicit IOWAIT(0) call issued by the GET intrinsic completed a 
pending remote MPE File System I/O without wait request instead of a 
remote DS/3000 I/O request. tonumber contains the file number 
associated with the completed File System request. 


An error occurred. Issue a PCHECK intrinsic call to determine what 
happened. 


The GET intrinsic receives the next request from a local master program and accepts an optional tag 
field (available in ztag). The GET intrinsic call implicitly issues an IOWAIT(0) intrinsic call. An 
ifun of 0 indicates that an IOWAIT error occurred. An zfun of 5 will occur only if you are executing 
MPE File System intrinsic calls without wait in your remote program and the implicit IOWAIT(0O) call 
completes a pending File System I/O request instead of the expected DS/3000 I/O request (in this 
case, you will have to issue another GET call after processing the completed File System I/O request in 
order to receive the expected DS/3000 I/O request). 


NOTE 


You must not use IOWAIT calls within a program 
containing DS/3000 GET calls. If you were to use an 
IOWAIT(0) call and it responded to a DS/3000 I/O 
request, your program would not be able to make any 
sense out of the information returned by the IOWAIT 
call. 
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PCHECK 


(Slave and Master callable) Returns an integer code specifying the completion status 
of the most recently executed DS/3000 
program-to-program intrinsic. 


SYNTAX 


tcode : =PCHECK(dsnum) ; 





FUNCTIONAL RETURN 


When the PCHECK intrinsic executes, it returns to the calling program a number (zcode) that specifies 
the completion status of the most recently executed DS/3000 program-to-program intrinsic. The 
various values of zcode are shown in Appendix A under the heading "DS/3000 Functional Errors." 


PARAMETERS 


dsnum integer by value 
MASTER PROGRAM: The link identifier returned by the particular 


POPEN intrinsic that initiated communication 
with the remote slave program. 


SLAVE PROGRAM: 0 (zero); no link identifier is returned to a 
slave program. 


CONDITION CODES 


CCE PCHECK request successfully completed. 

CCG (Not returned.) 

CCL PCHECK request denied because dsnum was invalid. 
OPERATION 


The PCHECK intrinsic returns an integer value that specifies the completion status of the most recently 
executed DS/3000 program-to-program intrinsic. 

















PCLOSE 


(Master callable) Terminates program-to-program communication with a 
remote slave program. 


SYNTAX 


PCLOSE (dsnum) ; 





PARAMETERS 


dsnum integer by value 


The line number returned by the particular POPEN intrinsic call which 
initiated communication with the remote slave program. 


CONDITION CODES 


CCE Successful completion. 
CCG (Not returned.) 
CCL Request denied; an error occurred. Issue a PCHECK intrinsic call to 


determine what happened. 


OPERATION 


The PCLOSE intrinsic terminates the remote slave program associated with dsnum. The particular 
communications line remains open. 


PCONTROL 


(Master callable) Exchanges tag fields with the remote slave program. 


SYNTAX 





PARAMETERS 

dsnum integer by value 
The link identifier returned by the particular POPEN intrinsic call which 
initiated communication with the remote slave program. 

ittag integer array 


A twenty-word array used for transmitting and receiving a tag field. The 
format of the tag field is defined by the master and slave programs and 
may serve any purpose you desire. 


CONDITION CODES 


CCE Request accepted by remote slave program. 
CCG Request rejected by remote slave program. 
CCL Request denied; an error occurred. Issue a PCHECK intrinsic call to 


determine what happened. 


OPERATION 


The PCONTROL intrinsic transmits a tag field to the remote slave program and accepts one in return. 
The remote slave program must issue a GET intrinsic call followed by either an ACCEPT or REJECT call 
to complete the PCONTROL operation. Both the ACCEPT and REJECT calls transmit a tag field back to 
the master program. 


Although this intrinsic was designed specifically for the exchanging of tag fields, you will notice that 
itag is an optional parameter (it is also optional for the ACCEPT and REJECT slave 
program-to-program calls). If the master program did not transmit a tag field, the returned tag field 
(if any) is not accessible. 


The PCONTROL activity is illustrated in Figure 6-1. 


PCONTROL Intrinsic 





MASTER 
Send control request and optional 
tag field. 





PCONTROL 


DS/3000 
BUFFER 


Send optional } 


tag field. 
ACCEPT 





or 


REJECT 





Figure 6-1. PCONTROL Activity. 





POPEN 


(Master callable) Initiates program-to-program communication with a 
remote slave program. 


SYNTAX 


4 4 maxdata] [: 


: OH 3: 





FUNCTIONAL RETURN 


‘When the POPEN intrinsic executes, it returns to the master program a number (dsnum) by which 
DS/ 3000 uniquely identifies the particular communications link. This number is analgous to the file 
number returned by the MPE FOPEN intrinsic in that it 1s used in all subsequent master 
program-to-program intrinsic calls to reference the remote slave program. 


PARAMETERS 

dsdevice byte array 
Contains a string of ASCII characters terminated by a space. This string 
must be the device class name, logical device number, or node name used in 
the :DSLINE or :REMOTE HELLO command that opened the 
communications line you will be using. 

progname byte array 
Contains a string of ASCII characters terminated by a space. This string is 
the name (with optional group and account names) of an MPE program file 
(residing on a disc connected to the remote HP 3000) containing the remote 
slave program. 


ttag integer array 


A twenty-word array that is used for transmitting and receiving tag fields. 
The format of the tag field is defined as part of the user’s application. 


Default: A tag field of all zeros is sent; the returned tag field (if 
any) is not available to the master program. 
entryname byte array 
Contains a string of ASCII characters terminated by a space. This string 1s 
the name of the entry point (label) at which execution of the remote slave 


program is to begin. 


Default: Primary entry point. 














param 


flags 


POPEN Intrinsic 


integer by value 

A word used to transfer control information to the new (remote) process. 
Any instruction in the outer block of code in the new process can access 
this information in location Q-4. 


Default: Word is filled with zeros. 


logical by value 


A word whose bits, if on, specify the loading options for the slave program: 


NOTE 


Bit groups are denoted using the standard SPL notation. 
Thus bit(15:1) indicates bit 15, bits(1 0:3) indicates bits 
10, 11, and 12. 


Bit(15:1) - (Always set on.) 

Bit(14:1) - LOADMAP bit. If on, a listing of the allocated (loaded) program 
is produced on the job/session list device. This map shows the Code 
Segment Table (CST) entries used by the new process. If off, no map is 
produced. 

Default: Off. 

Bit(1 3:1) - DEBUG bit. Bit must be off (0) -- no breakpoint can be set. 
Default: Off. 

Bit(12:1) - If on, the slave program is loaded in non-privileged mode. If 
this bit is off, the program is loaded in the mode specified when the 


program file was prepared. 


Default: Off. 


POPEN Intrinsic 


Bits(10:2) - LIBSEARCH bits. These bits denote the order in which remote 

libraries are to be searched for the slave program: 

00 System Library 

O01 - Account Public Library, followed by System Library. 

10 - Group Library, followed by Account Public Library and System 
Library. 

Default: 00 

Bit(9:1) - NOCB bit. If on, file system control blocks are established in an 

extra segment. If off, control blocks may be established in the Process 


Control Block Extension (PCBX) area. 


Default: Off. 


NOTE 


This bit should be set on if the slave program uses a large 
stack. 

Bits(7:2) - Reserved for MPE. Should be set to zero. 

Bits( 5:2) - STACK DUMP bits. Bits must be off (00). 

Default: 00 


Bit(4:1) - Reserved for MPE. Should be set to zero. 


NOTE 


The following bits (0:4) are ignored, because the bit pair 
(5:2) must be 00. 


Bit(3:1) - DL to QI bit. If on, the portion of the stack from DL to QI is 
dumped. If off, this portion of the stack 1s not dumped. 
Default: Off. 


Bit(2:1) - QI to S bit. If on, the portion of the stack from QI to S is dumped. 
If off, this portion of the stack is not dumped. 





stacksize 





dlsize 


maxdata 





buf size 








POPEN Intrinsic 


Default: Off. 


Bit(1:1) - Q-63 toS bit. If on, the portion of the stack from Q-63 to S is 
dumped. If off, this portion of the stack is not dumped. 


Default: Off. 


integer by value 


An integer (Z - Q) denoting the number of words assigned to the local stack 
area bounded by the initial Q and Z registers. 


Default: The same as that specified in the program file. 


integer by value 


An integer (DB - DL) denoting the number of words in the user-managed 
stack area bounded by the DL and DB registers. 


Default: The same as that specified in the program file. 


integer by value 


The maximum size allowed for the process stack (Z - DL) area in words. 
When specified, this value overrides the one established at 
program-preparation time. 


Default: If not specified, and not specified in program file either, 
MPE assumes that the stack will remain the same size. 


integer by value 


The size in words of the communications buffer (DS/3000 buffer) that is to 
be established by the remote DS/3000 software. It has a maximum value of 
4096 words. Note that this parameter defines the maximum number of 
words of data that can be transmitted by a PWRITE or PREAD intrinsic call. 


Default: Same size as the line buffer defined by the :DSLINE 
command (LINEBUF =) for the first :DSLINE issued to the 
dsdevice. Will never be smaller than 304 words. 


If no LINEBUF= is specified by the first : DSLINE 
command, then the default configuration length is used. If 
X.25 is being used, the default configuration length will be 
138. 


POPEN Intrinsic 


CONDITION CODES 


CCE Request accepted by remote slave program. 
CCG Request rejected by remote slave program. 
CCL Request denied; an error occurred. Issue a PCHECK intrinsic call to 


determine what happened. 


OPERATION 


The POPEN intrinsic creates and activates a process in the remote HP 3000 for the specified remote 
slave program (progname) and optionally transmits a tag field (t¢a@g) to that remote slave program. 
The remote slave program must issue a GET intrinsic call followed by either an ACCEPT or REJECT call 
to complete the POPEN operation. The remote slave program may transmit a tag field back to the 
master program as part of an ACCEPT or REJECT call. If the master program transmitted a tag field, 
then the returned tag field (if any) is available in «tag. If the master program did not transmit a tag 
field, then the returned tag field (if any) is not accessible. 


The bufsize parameter specifies the length in words of an area to be established by the remote 
DS/3000 software as a communications buffer. This buffer is established implicitly as part of the GET 
call that receives the POPEN request. The value will be the maximum size of a PREAD or PWRITE data 


buffer. 
NOTE 


The master program is limited to one slave program on 
each line. Thus, only one POPEN (to a given node) is 
permitted, assuming only one line connects the two 
systems. After a POPEN intrinsic call, the remote slave 
program remains activated, and both the 
communications link and the DS/3000 buffer remain 
intact, even if the POPEN request is rejected by the 
remote slave program. The meaning of a POPEN reject 
by the remote slave program must be established as part 
of the design of the user’s application. 


The POPEN activity is illustrated in Figure 6-2. 


POPEN Intrinsic 





1) Create and activate a process for 


(HP 3000) the remote slave program. (HP 1000) 
MASTER SLAVE 
2) Send optional tag field. 





Send optional 
tag field. 


ACCEPT 





REJECT 








Figure 6-2. POPEN Activity. 





PREAD 


(Master callable) Asks the remote slave program to return a block of data. 


SYNTAX 


Lgth:=PREAD(dsnum, target ,tcount[,itag}); 





FUNCTIONAL RETURN 


The PREAD intrinsic returns a positive integer value showing the length (Zgth) of the information 
transferred. If the tcount parameter in the PREAD call was positive, the positive value returned 
represents a word count; if the tcount parameter was negative, the positive value returned represents 
a byte count. 


PARAMETERS 
dsnum integer by value 
The link identifier returned by the particular POPEN intrinsic call which 
initiated communication with the remote slave program. 
target integer array 
The array into which data received from the remote slave program will be 
deposited. 
teount integer by value 
The requested number of words (if positive) or bytes (if negative) of data 
ttag integer array 


A twenty-word array used for transmitting and receiving a tag field. The 
format of the tag field is defined by the master and slave programs and 
may serve any purpose the user desires. 


CONDITION CODES 


CCE Request accepted by remote slave program. 
CCG Request rejected by remote slave program. 
CCL Request denied; an error occurred. Issue a PCHECK intrinsic call to 


determine what happened. 
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PREAD Intrinsic 


OPERATION 


The PREAD intrinsic transmits a read request to the remote slave program and optionally transmits a 
tag field from itag to the remote slave program. The remote slave program must issue a GET 
intrinsic call followed by either an ACCEPT or REJECT call to complete the PREAD operation. The GET 
call moves the tag field from the master program into the itag field provided in the remote slave 
program. The ACCEPT call moves the requested block of data from the remote program’s data buffer 
into the target in the master program, and it also sends the optional tta@g back to the master program. 
The REJECT call transmits no data; it only returns the optional tag field. If the master program did 
not transmit a tag field, the returned field (if any) 1s not accessible. 


The PREAD activity is illustrated in Figure 6-3. 


(HP 3000) (HP 1000) 
MASTER SLAVE 


Send read request and 
optional tag field. 
TARGET 


Send 
USER’S optional 
BUFFER tag field. 
ACCEPT 


~ (Send data from user's 
(Oo, ™ buffer to remote master 
Ar 
program) 


USER'S 
BUFFER 


REJECT 
(no data transmitted) 





Figure 6-3. PREAD Activity. 
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PWRITE 


(Master callable) Sends a block of data to the remote slave program. 


SYNTAX 








PARAMETERS 
dsnum integer by value 
The link identifier returned by the particular POPEN intrinsic call which 
initiated communication with the remote slave program. 
target integer array “- 
The array from which data will be transmitted to a remote slave program. | 
teount integer by value 
The requested number of words (if positive) or bytes (if negative) of data. 
itag integer array “sy 


A twenty-word array used for transmitting and receiving a tag field. The 
format of the tag field is defined by the master and slave programs and 
may serve any purpose the user desires. 


CONDITION CODES 


CCE Request accepted by remote slave program. - 
CCG Request rejected by remote slave program. 
CCL Request denied; an error occurred. Issue a PCHECK intrinsic call to 


determine what happened. 


OPERATION 


The PWRITE intrinsic transmits a block of data (number of words or bytes = tecount) from target to 

the DS/3000 buffer in the remote HP 3000, and optionally transmits a tag field from ztag to the 

remote slave program. The remote slave program must issue a GET intrinsic call followed by either an 

ACCEPT or REJECT call to complete the PWRITE operation. The GET call moves the tag field from the 

master program into the ttag field provided in the remote slave program. The ACCEPT call moves the 

data from the remote DS/3000 buffer into the remote slave program’s buffer, and it also sends the 

optional ztag back to the master program. The REJECT call refuses the write request (the data in the om 
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PWRITE Intrinsic 





| DS/3000 buffer is no longer accessible to the slave program) and returns the optional tag field to the 
oe master program. 


The PWRITE activity is illustrated in Figure 6-4. 


(HP 3000) (HP 1000) 
(data) 


PWRITE 





Send write request, optional 
tag field, and data. ; DS/3000 


USER’S 
BUFFER 
ACCEPT 


BUFFER 


TARGET (data moved from DS/3000 / 


MASTER Send optional buffer to user's buffer) 


tag field. \ 
USER'S 
BUFFER 


or 


REJECT 
{data lost to user's program) 





Figure 6-4. PWRITE Activity. 
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REJECT 


(Slave callable) Rejects the request received by the preceding GET 
intrinsic call and returns an optional tag field to the 
remote master program. | om 
SYNTAX "eis 


REJECT ( [itag]); 





PARAMETERS 
itag integer array 

A twenty-word array used for transmitting a tag field. The format of the 

tag field is defined by the user’s master and slave programs. 
CONDITION CODES a 
CCE Response transmitted successfully to the remote master program. 
CCG (Not returned). 
CCL An error occurred. Issue a PCHECK intrinsic call to determine what 

happened. : 

“ 

OPERATION 


The REJECT intrinsic rejects the request received by the most recent GET intrinsic call and transmits 
an optional tag field (i tag) back to the remote master program. 
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PTOP Communications 


INTERFACING WITH COBOL AND BASIC 





Access to the program-to-program communications capability is available to ANS COBOL (COBOL/I) 
and BASIC users only through the interface routines described in Appendices B and C, respectively. 


Programs written in SPL, FORTRAN, and COBOL II/3000 can use the PTOP intrinsics described in 
this section. 


PTOP EXAMPLE 


This example shows how two programs can communicate with one another by using the master and 
slave program-to-program intrinsics. The comments included within each program tell what is 
happening. 





Master Program 


1 $CONTROL USLINIT,ADR,MAP,CODE 
2 BEGIN 


COMMENT 
NAME OF PROGRAM IS MASTERP. 
THE SOURCE IS MASTERS. 
THIS PROGRAM IS TO BE RUN ON THE MASTER CPU. IT WILL START 
THE "SLAVEP" PROGRAM ON THE SLAVE CPU. THE PROGRAM WILL THEN 
RECEIVE A KNOWN TEST PATTERN FROM THE USER TERMINAL, WRITE IT 
10 TO THE REMOTE DISC FILE, READ IT BACK 5 TIMES, AND PRINT IT 
11 ON THE LOCAL LP 5S TIMES. 
12 THE TRANSFER OF DATA IS DONE THRU PTOP.; 


OONOD oD WwW 





13 

14 

15 INTEGER 

16 ERROR, 

17  LINE’NUM, 

18 6, 

19 J, 

20 LPDEV’NUM; 

21 

22 BYTE ARRAY DS’DEVICE(0:6):=" "; 


23 BYTE ARRAY LPDEV(0:2):="LP "; 

24 BYTE ARRAY LPFILE(0:6):="LPFILE "; 

25 BYTE ARRAY MSG(0:79); 

26 BYTE ARRAY PROG’NAME(0:19):="SLAVEP.PUB.SUPPORT "; 


29 LOGICAL ARRAY IOBUF (0:39); 

30 LOGICAL ARRAY ITAG(0:19):=20(%020040) ; 
31 LOGICAL ARRAY MSGW(#*)=MSG; 

32 LOGICAL ARRAY DS’DEVW(#)=DS’ DEVICE; 
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INTRINSIC DEBUG,FCLOSE ,FOPEN ,FWRITE,PCONTROL ; 
INTRINSIC PCLOSE, POPEN,PREAD, PRINT, PWRITE,READ; 


MOVE MSG:=" INPUT NAME OF DSDEVICE"; 
PRINT (MSGW, -28,0); 
READ(DS’DEVW,-7) ; 


MOVE MSG:="" POPEN ISSUED"; 
PRINT (MSGW,-18,0); 


LINE ’NUM: =POPEN (DS “DEVICE, PROG’ NAME ,ITAG); 
IF <> THEN 


BEGIN 
PRINT(ITAG,20,0); 
ERROR := 13 
GO TO ERR’ PROC; 

END 

ELSE 


PRINT(ITAG,20,0); 


MOVE MSG:=" POPEN COMPLETED SUCCESSFULLY"; 
PRINT (MSGW, -33,0); 


LPDEV’NUM: =FOPEN(LPFILE,4,1,40,LPDEV) ; 
IF <> THEN BEGIN ERROR:=2;GO TO ERR’PROC; END; 


MOVE MSG:="IN PUT TEST RECORD MAX. 80 CHAR"; 
PRINT (MSGW, -30,0); 


MOVE IOBUF:=" "3; <<CLEAR OUT BUFFER AREA>> 
MOVE IOBUF (1):=IOBUF, (39); 


READ(IOBUF ,-80); <<GET RECORD TO WRITE>> 


PWRITE(LINE’NUM,IOBUF,40); <<SEND RECORD TO REMOTE>> 
IF <> THEN BEGIN ERROR: =3;GO TO ERR’PROC; END; 


MOVE MSG:=" DISC FILES BEING XFERRED FROM REMOTE”; 
PRINT (MSGW, -41,0); 
J:=-13; <<START READING FROM REMOTE>> 
WHILE (J:=J+1)<5 DO 
BEGIN 
MOVE MSG:=" PREAD ISSUED"; 
PRINT (MSGW,-19,0); 


MOVE IOBUF:=" "; 
MOVE IOBUF (1) :=IOBUF , (39); 


I:=PREAD(LINE’ NUM, IOBUF ,40,ITAG) ; 


IF = THEN 
BEGIN 
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88 IF J=4 THEN 
> 89 BEGIN 

eo 90 MOVE MSG:=" ALL DISK RECORDS XFERRED"; 
91 PRINT (MSGW, -29,0); 
92 END; 
93 END 
94 ELSE 
95 BEGIN ERROR: =4;GO TO ERR’PROC; END; 
96 FWRITE(LPDEV’NUM, IOBUF ,I ,0) ; 
97 IF <> THEN BEGIN ERROR:=4;GO TO ERR’ PROC;END; 
98 END; 
99 


100 FCLOSE(LPDEV’NUM,0,0); 

101 PCLOSE(LINE’NUM) ; 

102 IF <> THEN BEGIN ERROR:=5;GO TO ERR’ PROC;END; 
103 MOVE MSG:="END OF MASTER PROGRAM"; 

104 PRINT(MSGW,-21,0); GO TO END’IT; 


105 
106 ERR’PROC: <<HANDLE ERROR CONDITIONS>> 
107 DEBUG; 





108 FCLOSE(LPDEV’NUM,0O,0); 

109 PCLOSE(LINE’NUM); 

110 MOVE MSG:="ERROR, END MASTER PROGRAM’ ; 
111 PRINT (MSGW,-25,0); 

112 

113 END’IT: END. 





Slave Program 
1 $CONTROL USLINIT,ADR,MAP,CODE 


2 
3 BEGIN 

4 COMMENT 

5 THE NAME OF THIS PROGRAM IS SLAVEP. 

6 THE NAME OF THE SOURCE IS SLAVES. 

4 THIS PROGRAM IS TO BE COMPILED AND PREP’ED ON THE 

8 SLAVE HP3000 SYSTEM. IT WILL BE INITIATED FOR EXECUTION 
9 BY THE MASTER. THE FUNCTION OF THIS PROGRAM IS TO 

10 LOAD A DISC FILE WITH 5 KNOWN TEST PATTERNS THAT WILL 
11 BE TRANSFERRED TO THE MASTER 5 TIMES AND PRINTED ON THE 
12 MASTER’S LINE PRINTER S TIMES; 





13 

14 

15 INTEGER 

16 ERROR, 

17 DISK’FILENUM, 

18 «CT, 

19 IL, 

20  IONUMBER, 

21 J3 

22 

23 BYTE ARRAY MSG(0:79); 
Cc 24 BYTE ARRAY TEST(0:4):="TEST "; 
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LOGICAL ARRAY DISK’ BUF (0:39); 
LOGICAL ARRAY ITAG(0:19) :=20(020040) ; 
LOGICAL ARRAY MSGW(#*)=MSG; 


INTRINSIC FOPEN , DEBUG ,FWRITEDIR,FREADDIR,FCLOSE; 
INTRINSIC GET,ACCEPT,PRINT ,READ, REJECT; 


IL:=40; 
MOVE MSG:="ISSUING A GET (REMOTE)"; 
PRINT (MSGW, -22,0); 
I:=GET(ITAG); <<GET FOR POPEN>> 
IF < THEN 
BEGIN 
MOVE ITAG:="ERROR ON GET;POPEN’; 
GO TO ERR’ PROC; 
END; 


IF I=1 THEN 
BEGIN 
MOVE MSG:="POPEN RCVD...ISSUING AN ACCEPT (REMOTE)"; 
PRINT (MSGW,-39,0); 
ACCEPT(ITAG); <<ACCEPT FOR POPEN>> 
END; 


MOVE ITAG:="POPEN ACCEPT SUCCESSFUL (REMOTE)"; 


DISK’ FILENUM: =FOPEN (TEST, 4,%104,-80,,,,1,1,10D); 
IF <> THEN BEGIN ERROR:=1;GO TO ERR’PROC; END; 


I:=GET; <<TEST REC FROM MASTER>> 
IF <> THEN BEGIN ERROR: =2; GO TO ERR’PROC; END; 
IF I=3 THEN <<PWRITE RECEIVED>> 
BEGIN 
ACCEPT( ,DISK’ BUF); 
IF <> THEN BEGIN ERROR:=3; GO TO ERR’PROC; END; 
END; 


T:=-13 <<START WRITING TEST FILE>> 
WHILE(I:=I+1) < 5 DO 
BEGIN <<WRITE REC TO DISK>> 
FWRITEDIR(DISK“FILENUM,DISK’ BUF ,40 ,DOUBLE(I)); 
IF <> THEN BEGIN ERROR:=4; GO TO ERR’PROC; END; 


END; <<END WRITING TEST FILE>> 


J:=-1; <<SEND DISK FILE TO MASTER>> 
WHILE (J:=J+1)<5 DO 
BEGIN 
MOVE MSG:="ISSUING A GET (REMOTE)”; 
PRINT (MSGW,-22,0); 
I:=GET(ITAG,IL,IONUMBER) ; 
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IF < THEN BEGIN ERROR:=5; GO TO ERR’PROC; END; 
IF I=2 THEN 
BEGIN 
MOVE MSG:="PREAD RCVD...ISSUING AN ACCEPT"; 
(REMOTE) "; 
PRINT (MSGW, -39,0); 
END 
ELSE 
BEGIN ERROR:=6;GO TO ERR’ PROC; END; 
MOVE DISK’ BUF :=%020040; 
MOVE DISK’ BUF (1):=DISK’ BUF (0), (39); 
FREADDIR(DISK’ BUF ,40,DOUBLE (J) ); 
IF <> THEN BEGIN ERROR:=7;GO TO ERR’ PROC; END; 
ACCEPT (ITAG,DISK’ BUF , 40) ; 
IF <> THEN BEGIN ERROR:=8;GO TO ERR’PROC; END; 


END; 
FCLOSE(DISK’FILENUM,O,0); GO TO END’IT; 


ERR’ PROC: <<HANDLE ERROR CONDITIONS>> 
DEBUG; <<WILL PROMPT AT MASTER SIDE TERMINAL>> 
REJECT ; 
T:=GET; <<ALLOW PCLOSE>> 


101 GO TO ERR’ PROC; 


102 


103 END’IT: END; 


PTOP Communications 
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SECTION 


NETWORK FILE TRANSFER 





~H 





The Network File Transfer (NFT) program runs on an HP 3000 Computer System to provide the 
ability to copy disc files efficiently. When initiated over a DS/3000 communications link, the NFT 
program can copy a file to or from any other adjacent HP 3000 computer which also provides this 
service. 


FEATURES OF NFT 


e You can initiate copy operations from sessions, jobs, or programs. 


e DSCOPY can be used to copy users’ files and MPE system files, as well as data management files, 
such as KSAM/ 3000 files. 





e There is only one NFT command to learn -- :DSCOPY. 


e There are two intrinsics: DSCOPY and DSCOPYMSG. The intrinsics are callable from programs 
written in SPL/3000, COBOL, Pascal, FORTRAN, and BASIC. 


e NFT can be used in Interactive Mode to submit a series of copy requests. When a DSCOPY 
command or intrinsic initiates Interactive Mode, users’ requests are placed in a transaction file 
whose formal designator is DSCOPYI. The default for this file is $STDINX. This file must be 
unnumbered. 





e NFT can record a history of all copy operations performed by DSCOPY requests. The history 
report can be printed to $STDLIST, as well as to a secondary file. The secondary file has the 
formal designator DSCOPYL. 


e You can initiate a copy operation from a system other than the system(s) where the source and 
target files are located. 





e NFT can efficiently copy disc files within your local HP 3000. 
e The files referenced by a DSCOPY command (or intrinsic) may reside on system or private volumes. 


File transfers can involve one or more computers. In all transfers, there are three distinct rolesa 
system can play: 


1. The initiator is always the system where the :DSCOPY command originates. The initiator 
functions only in an outgoing sense. It is similar to PTOP operation, where the PTOP 
master program always issues a POPEN out across a DS line to cause a slave to be created 
and activated on a remote system. 


2. The producer is the source computer where the file that is to be copied resides. 


3. The consumer is the target computer where the new file will reside. 





Network File Transfer 


You should remember that one system may be performing two or all three of these roles. 


When a DSCOPY request names a remote source, the DS line to that computer must be open and a 
remote session must exist. The same is also true when a remote target is specified. 


When DSCOPY is used to transfer files over two or more systems, the following restrictions apply: 


1. DSCOPY must be initiated only from the master side of the DS line. The slave (remote) side 
cannot be the initiator of a DSCOPY command. 


2. DSCOPY must not be initiated programmatically from either a master or a slave PTOP 
program in any direction. 
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SYNTAX 





° 
9 


: pscopy/ [source ] rot target] ]] 





where the command syntax has the following meanings: 


source as 





target -- 





To submit a series of transfer requests, omit all of the source and target parameters to initiate 
Interactive Mode. NFT prompts you for input and, after the transfer completes, prompts you again 
for the next transfer request. 





Terminate Interactive Mode by typing // or (CONTROL)Y. 
PARAMETERS 


sfile Identifies the file to be copied. The name can be written in the following 
format: 


sfile[\lockword] [.groupname] [.accountname] 





If the source file is in a group.account different from the requestor’s 
log-on group.account, the requestor must have read and lock access to 
the source file. (Lock access means that the file cannot be opened for 
writing while : DSCOPY is copying it.) 


sdsdev The device classname, logical device number, or node name that was used to 
open the communications link to the remote computer where the source file 
resides. 


Default: The local system (that is, the system where the transfer 


request is submitted). 


sdev The classname or logical device number of the disc where the source file 
resides. 





Default: DISC. 
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tfile 


tdsdev 


tdev 


FCODE= 
sourcefilecode 


USE 


Available 


Breakable? 


* 


Specifies the file to receive the data. The name can be written in the 
following format: 


tfile[\Lockword] [.groupname] [ .accountname] 


Default: The new file has the same filename as the source file. The 
default groupname and accountname are the log-on 
groupname and accountname. Security is on for the new 
file, even though the source file may have been released. 


The device classname, logical device number, or nodename that was used to 
open the communications link to the remote computer where the target file 
will reside. 


Default: : DSCOPY copies the sourcefile to the local computer and 
assigns the same filename as the sourcefile name. If the 
source computer is the local system, this default causes a 
file system error (because the file already exists). 


Means the target dsdevice (the target computer) is the same as the source 
dsdevice (the source computer). 


The device classname or logical device number of the disc where the new 
file should reside. 


Default: DISC 
Applies to privilege mode files only. Specifies that the new file will have 


the same negative file code as the source file. System Manager or Privilege 
Mode capability is required for both the source and target file creators. 


in Session? YES 
in Job? YES 
in Break? NO 
Programmatically? No* 
No** 


Call the DSCOPY intrinsic rather than use the COMMAND intrinsic. 


** Use (ONTROL)Y, rather than (BREAK). 
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OPERATION 


NOTE 


is disabled during DSCOPY. 


If you enter (CONTROL)Y during a copy operation, DSCOPY 
prints the percentage of the transfer that is complete 
and prompts whether to cancel or continue the 
operation. 


Source and Target Files 


In a DSCOPY command, source and target files are referenced as defined by the systems upon which 
they reside. 


There 1s no default for a sourcefile. 


A default for a targetfile is derived from the sourcefile. The default consists of the first sequence of 
characters in the sourcefile name which constitutes a legal HP 3000 file name. For example: 


:DSCOPY SFILE.SGROUP,SNODE 


Here the source file is SFILE (in group SGROUP on a remote system). The targetfile is generated in the 
users’ log-on group (on the local system) and is assigned the default name SFILE. The characteristics 
of the new file are the same as those of the source file. 


In order to transfer a file with a negative file code (ie., a privilege mode file), the FCODE= parameter 
must be included in the command string, and the log-on user on both the source and target systems 
must have System Manager (SM) or Privilege Mode (PM) capability. (Remember that the user 
requesting the transfer (the initiator) is not necessarily the log-on user at the target (the consumer).) 
After a successful copy operation, the new file has the same negative file code as the source file (as 
specified by sourcefilecode). For example: 


:DSCOPY SFILE,SNODE TO TFILE;FCODE=-401 
When copying KSAM files, both the data file and its key file are copied. The DSCOPY user can 
specifically name a data file/key file pair by enclosing the file names in quotes and separating them 
by a comma. For example: 


:DSCOPY SFILE TO "“DATAFILE,KEYFILE' 


When a user specifies a source KSAM data file and the NFT subsystem must generate a default key 
file, it uses the data file name and appendsa K. For example: 


:DSCOPY SFILE, LINE1 TO TFILE, LINE2 
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In the case where SFILE is a KSAM data file, the new data file on the computer connected to LINE2 
will be named TFILE and the associated key file will be named TFILEK by default. 


NOTE 


DSCOPY cannot copy to a back-referenced target file 
(e.g., the form DSCOPY SFILE TO #TFILE is not 
permitted). 


EXAMPLES 


Local Copy 
To make a local copy of SFILE and name the new file TFILE, use either of the following: 


:DSCOPY SFILE TO TFILE or :DSCOPY SFILE; TFILE 





LOCAL 


The following example copies a file named SFILE from another group on the local system (SGROUP) 
into a file in the log-on group. The new file is also named SFILE. 


:DSCOPY SFILE.SGROUP 


SGROUP 





LOCAL 
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Remote-to-Local Copy 


To copy a file from the computer connected to DS line SYSA into your log-on group (on the local 
system), enter: 


:DSCOPY SFILE,SYSA;TFILE 


LOCAL 









| KSYSB 


REMOTE 











i=] 
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Local-to-Remote Copy ; “ 


To copy a file named SFILE (on the local system) to the computer attached to DS line SYSB and name 
the new file SFILE, enter: 


:DSCOPY SFILE TO ,SYSB 


LOCAL 






SFILE 





/ KSYSB 


REMOTE 
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Remote Copy 

An asterisk (#) means the target system is also the source system. The following example copies a file 
named SFILE to a new file named TFILE. Both files reside on the remote computer connected to the 
dsline named SYSA. 


:DSCOPY SFILE,SYSA TO TFILE,* 


LOCAL 








REMOTE 
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Remote-to-Remote Copy 


The next example illustrates a command that copies a file from one remote system to another. In this 
case, the communications lines to both remote computers must be open and a remote session must exist 
on each system. 


:DSCOPY SFILE,SYSA TO TFILE,SYSB 






REMOTE 


REMOTE 
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INTERACTIVE MODE 


To execute a series of transactions interactively, enter the :DSCOPY command without parameters. 
Now the system prompts you for input with the word DSCOPY and accepts your response from the file 
DSCOPYI (whose default is $STDINX). 


The syntax required for your response follows the format already described for source and target 
parameters. 


You can issue MPE comands while in Interactive Mode by entering a colon (:) before the command. 
The MPE commands allowed in Interactive Mode are those allowed by the COMMAND intrinsic. 


Note the following about Interactive Mode: 


e Tocontinue your response on the next line, enter an ampersand (&) as the last non-blank 
character on the current line and press (RETURN). A continuation prompt is printed so that you can 
continue your response. 


e Tocancel a response while entering a line, use (CONTROL)X. 


e To terminate Intractive Mode, enter // or (CONTROL)Y. 


Multiple Transactions 


DSCOPY also allows you to perform multiple file transfers by redirecting DSCOPYI to a disc file 
containing the individual file transactions. To use this mode of DSCOPY, simply create an 
unnumbered ascii file, with one transfer per line, using the following format: 


SFILE[,SDSDEV] TO TFILE[,TDSDEV] 


where SFILE is the source file, TF ILE 1s the target file, and SDSDEV or TDSDEV is the device class 
name, LDEV number, or node name that was used to open the communications link to the remote 
computer. Keep this file, unnumbered, using a filename of your choice. Next, enter an MPE file 
equation that references your transaction file to DSCOPYI, and then enter the :DSCOPY command 
without parameters. In the following example, user input is underscored, and the existence of a remote 
session is assumed. 


NOTE 


Imbedded MPE commands are not supported if DSCOPYI has 
been redirected to a file other than the default, $STDINX. 


‘DSCOPY 


Example 


EDITOR 
HP 32201A.7.17 EDIT/3000 TUE, OCT 29, 1985, 8:35 AM 
(C) HEWLETT-PACKARD CO. 1985 
/adD 
1 SFILEA,REMOTE1 TO TFILEA 
2 SFILEB,REMOTE1 TO TFILEB 
3 SFILEC,REMOTE1 TO TFILEC 
47 
/K XFERFILE,UNN 
E 


END OF PROGRAM 
sFILE DSCOPYI=AFERFILE 
: DSCOPY 


Network File Transfer [HP32185B.52.00] (C) Hewlett-Packard Co. 1980 


DSCOPY SFILEA,REMOTE1 TO TFILEA 
New file created -- TFILEA.TGROUP.TACCT -- 
Succeeded. 


DSCOPY SFILEB,REMOTE1 TO TFILEB 
New file created -- TFILEB.TGROUP.TACCT -- 
Succeeded. 


DSCOPY SFILEC,REMOTE1 TO TFILEC 
New file created -- TFILEC.TGROUP.TACCT -- 
Succeeded. 


END OF SUBSYSTEM 


Event Recording 


DSCOPY produces printed output to document user input and copy results. This output may be sent to 
a primary file and/or a secondary file, either of which may be disabled. The primary file is $STDLIST 
and the secondary file has the formal designator DSCOPYL. All user requests and DSCOPY prompts are 
printed on $STDLIST and echoed on the secondary file (and on the primary, if not duplicative). 
Primary output is enabled by a :DSCOPY command, or by the DSCOPY intrinsic with the OPT 
parameter set to 4, 5, or 6 (refer to the parameters of the DSCOPY intrinsic). Output for the secondary 
file, DSCOPYL, defaults to $NULL so that secondary output is disabled by default. It can be enabled by 
using a :F ILE command to equate DSCOPYL to a file or a line printer, or to $STDLIST. 
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PROGRAMMATIC MODE 


Programs can use the DSCOPY intrinsic to copy disc files. 


Programs can also print a message which corresponds to the result code returned by a DSCOPY intrinsic 
call. The DSCOPYMSG intrinsic is used for this purpose. 


is disabled during DSCOPY. After you finish with the DSCOPY intrinsic, you must call 
FCONTROL 15 to set back on. See the MPE Intrinsics Manual for details. 


The rules for using the intrinsics are consistent with those for using other MPE intrinsics. Specifically, 
the following rules apply. 


Both intrinsics can be called from programs written in the SPL/3000, COBOL, Pascal, FORTRAN, 
and BASIC languages. 


Calling sequences for all of the languages are basically the same. 

All parameters are passed by reference. 

The intrinsics are not option variable. 

Neither of the intrinsics are typed (returns a parameter as its value). 
Neither returns a condition code (they both return a result). 

Split stack calls are not allowed. 


For COBOL, data types should be defined as follows: 


Data Type Data Description 

Numeric PICTURE S9(4) COMPUTATIONAL 

Alphanumeric PICTURE X(n) or PICTURE A(n) 

Numeric Array ss S$9(4) COMPUTATIONAL SYNCHRONIZED OCCURS n 
IMES 


For Pascal, the following special data type should be defined: 


Data Type Data Description 


SHORTINT -32768. .32767 


DSCOPY Intrinsic 


Allows programmatic use of DSCOPY 


SYNTAX 


DSCOPY (opt, spec, result); 





PARAMETERS 


opt 


spec 


logical 


opt controls the primary output (i.e. output to $STDLIST) and specifies the 
type of copy operation. 


Bits 0 through 12 are reserved for future use and should be set to zero. The 
remaining bits can be set to indicate the following: 


Value Meaning 
0 Single transaction; primary output disabled. 
l Multiple transactions; return after first 
unsuccessful transaction; primary output 
disabled. 
2 Multiple transactions; return after all 


transactions have been attempted or after an 
internal error occurs; primary output disabled. 


4 Single transaction; primary output enabled. 

5 Multiple transactions; return after first 
unsuccessful transaction; primary output 
enabled. 

6 Multiple transactions; return after all 


transactions have been attempted or after an 
internal error occurs; primary output enabled. 
logical array 
The logical array should contain ASCII text terminated by an 8-bit binary 
zero. In the single transaction case, the syntax required is the same as for 
the DSCOPY command parameters. 
In the multiple transaction case, the array should contain only a zero. Zero 


causes NFT to read the copy request from the DSCOPYI file (whose default 
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is $STDIN). This file must be unnumbered. 


result logical array 


A two-word array returned to the caller that indicates the outcome of the 
intrinsic call. 


result(0) Indicates the copy operation was successful. 
Any other value represents an error as defined in 
"DSCOPY Error Messages" listed in Appendix A. 


result(1) Shows the number of files that were 
successfully copied. 


OPERATION 

Simultaneous DSCOPY requests cannot be issued from two processes in the same session. 
The only valid values for the opt parameter are: 0, 1, 2, 4, 5, or 6. 

The ASCII text passed by the spec parameter must be terminated by a binary zero. 
The values passed in the parameters are verified as being in bounds and valid. 

The system creates the NFT process and passes the contents of opt and spec to it. 
The specified files are copied by the NFT process. 


The intrinsic returns the result to the user. 


EXAMPLES 


COBOL Calling Sequence 

CALL "“DSCOPY" USING OPT, SPEC, RESULT. 
OPT Numeric data item. 

SPEC Alphanumeric data item. 


RESULT Numeric array of two or more data items. 


FORTRAN Calling Sequence 


CALL DSCOPY (OPT, SPEC, RESULT) 


OPT INTEGER#2 variable 
SPEC CHARACTER array 


RESULT An array of two or more INTEGER#e variables 


BASIC Calling Sequence 


CALL BDSCOPY (0, S$, R) 


0 Numeric variable 
S$ A string variable 
R An array of two or more numeric variables 


Pascal Calling Sequence 


DSCOPY (OPT, SPEC, RESULT); 


OPT SHORTINT variable 
SPEC PACKED ARRAY OF CHAR array 
RESULT INTEGER variable 


SPL Calling Sequence 
DSCOPY (OPT, SPEC, IRESULT); 
OPT Logical 
SPEC(0:30) Logical Array 


IRESULT (0:4) Logical Array 





























DSCOPYMSG Intrinsic 


Prints the result code returned by DSCOPY. 
SYNTAX 


DSCOPYMSG (result, fnum, r); 





PARAMETERS 


result logical array 
The two-word result returned by the DSCOPY intrinsic. 
0 = DSCOPY was successful. 
n = An error occurred. Refer to the Error Messages in Appendix A. 
frum integer by value 
When fnunrO, the message associated with result is printed on $STDLIST. 
When fnumcontains a file number returned by an FOPEN call, the message 
associated with result is written to the file. 
r integer 
Result returned by this DSCOPYMSG call. 


0 = Successful call 
n = Unsuccessful call. Refer to the Error Messages in Appendix A. 


EXAMPLES 


COBOL Calling Sequence 

CALL “DSCOPYMSG" USING RESULT, FNUM, R. 
RESULT An array of two or more data items. 
FNUM A numeric data item. 


R A numeric data item. 


FORTRAN Calling Sequence 
CALL DSCOPYMSG (RESULT, FNUM, R) 


RESULT An array of two or more INTEGER#??2 variables. 


FNUM INTEGER#??2 variable 


R INTEGER? ?2 variable 


BASIC Calling Sequence 


CALL BDSCOPYMSG (R, F, RO) 


R An array of two or more numeric variables 
F An integer variable 
RO An integer variable 


Pascal Calling Sequence 
DSCOPYMSG (RESULT, FNUM, R); 
RESULT |= INTEGER variable 
FNUM SHORTINT variable 


R SHORTINT variable 


SPL Calling Sequence 
DSCOPYMSG (IRESULT, FNUM, R); 
IRESULT(0:4) Logical Array 
FNUM Integer 


R Integer 

















PROGRAMMATIC EXAMPLES 


A very simple example of a programmatic DSCOPY request is shown coded in the COBOL, FORTRAN, 
BASIC, Pascal and SPL/3000 languages. 


The example copies a file (NFTTEST) to a new file (TEMP1). The source file resides on the local 
machine, and the new file will be created on a remote machine connected to line "HDS." 


DSCOPY COBOL Example 


1 $CONTROL CODE 

1.1 $TITLE " DSCOPY INTRINSIC TEST" 
1.2 IDENTIFICATION DIVISION. 

1.3 PROGRAM-ID. DSCOPYOO. 

1.4 AUTHOR. SUZANNE FLAHERTY. 

1.5 DATE-WRITTEN. APRIL 1980. 

1.6 DATE-COMPILED. 
1.7 REMARKS. 

1.8 THIS PROGRAM DOES A SIMPLE DSCOPY INTRINSIC CALL. 
1.9 ENVIRONMENT DIVISION. 

2 CONFIGURATION SECTION. 

2.1 SOURCE-COMPUTER. HP3000 
2.2 OBJECT-COMPUTER. HP3000 
2.3 DATA DIVISION. 
2.4 WORKING-STORAGE SECTION. 

2.5 01 OPT PIC $9(4) COMP VALUE 0. 

2.6 01 STRING1. 

2.7 02 ASCIIPART PIC X(24) VALUE "NFTTEST TO TEMP1,HDS". 
2.8 02 TERMINATOR PIC S9(4) COMP VALUE 0. 

2.9 01 RESULT1. 

3 02 RESULT2 PIC S9(4) COMP OCCURS 2 TIMES. 

3.1 PROCEDURE DIVISION. 

3.2 BEGINLABEL. 

3.3 CALL INTRINSIC "“DSCOPY" USING OPT, STRING1, RESULT1. 
3.4 STOP RUN. 


DSCOPY FORTRAN Example 


25 $CONTROL MAP,LIST,CODE ,CROSSREF , LOCATION , STAT 


26 PROGRAM DSCOPY 

27 CHARACTER#40 STRING1 

28 INTEGER#2 FNUM, R 

29 INTEGER#2 OPT 

30 INTEGER ARRAY IRESULT(4) 

31 SYSTEM INTRINSIC DSCOPY, DSCOPYMSG 

32 C 

33 DATA STRING1/20OHNFTTEST TO TEMP1,HDS/ 
34 C 

35 C THIS PROGRAM DOES A DSCOPY INTRINSIC REQUEST 
36 C 

37 OPT=0 


Network File Transfer 


38 FNUM=0 

39 CALL DSCOPY(OPT, STRING1, IRESULT) 

40 IF (IRESULT .GT. 0) CALL DSCOPYMSG(IRESULT, FNUM, R) 
41 STOP 

42 END 


DSCOPY BASIC Example 


10 REM THIS WILL DO A SIMPLE DSCOPY REQUEST 
20 DIM A$[30],R[4] 

30 O0=R2=Z=0 

40 MAT R=ZER 

50 A$=" NFTTEST TO TEMP1,HDS " 

60 PRINT A$ 

70 CALL BDSCOPY (0,A$,R[#] ) 

80 IF R[1] <>O0 THEN PRINT " ERROR IN DSCOPY. ERROR= ",R[1] 
90 IF R[1] <>0 THEN CALL BDSCOPYMSG(R[#],Z,R2) 
100 STOP 

110 END 


DSCOPY Pascal Example 


PROGRAM DSCOPY ; 


TYPE 
SHORTINT = -32768. .32767; 
VAR 
OPT,FNUM,R : SHORTINT; 
RESULT : INTEGER; 
SPEC : PACKED ARRAY [1..127] OF CHAR; 


PROCEDURE DSCOPY; INTRINSIC; 
PROCEDURE DSCOPYMSG; INTRINSIC; 
BEGIN 
SPEC:=’NFTTEST TO TEMP1,HDS’; 
OPT :=0; 
FNUM:=0; 
DSCOPY (OPT, SPEC, RESULT) ; 
IF (RESULT > 0) THEN DSCOPYMSG(RESULT, FNUM,R); 
END. 


DSCOPY SPL/3000 Example 


1 $CONTROL USLINIT,CODE 

2 BEGIN 

INTEGER FNUM:=0,R:=0; 

3 LOGICAL OPT:=0; 

5 LOGICAL ARRAY SPEC(0:30), IRESULT(0:4); 
6 INTRINSIC DSCOPY, DSCOPYMSG; 

¢ MOVE SPEC:="NFTTEST TO TEMP1, HDS"; 

8 

9 

1 


SS 


DSCOPY (OPT ,SPEC, IRESULT) ; 
IF IRESULT > O THEN DSCOPYMSG(IRESULT,FNUM,R) ; 
O END. 


7-20 
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DS APPLICATION DESIGN 


DS/3000 is particularly useful in applications that involve transaction processing and that are 
geographically or functionally dispersed. Any local-system command can be executed remotely through a 
simple extension to that command. Many operating system intrinsics are also extended in a similar 
fashion. No knowledge of the communication protocol or physical link being used is required of the 
terminal user or application programmer. Every application-level capability operates transparently across 
each connection-level alternative. 


DS/3000 on the HP 3000 provides facilities for point-to-point connection between processors. These 
connections can be made on a variety of types of communications lines, including switched (dial-up), 
leased, or hardwired, and they can also be mixed throughout the network. Applications can easily obtain 
access to systems more than one "hop" away, through multiple :REMOTE HELLO log-ons. In addition, HP 
3000 computers can connect to X.25 packet-switched networks and communicate across those networks 
with HP 1000 or other HP 3000 computers using the DSN/X.25 software. In fact, DS/3000 can 
maintain concurrent connections to multiple remote systems, and/or multiple connections to the same 
remote system, over a single physical link to the X.25 network. 


DS/3000 requires users to pass all of the security checks imposed by MPE (such as passwords) when 
logging on to a remote system. DS/3000 also provides additional security features applicable only to a 
network environment. For example, the operator can restrict incoming or outgoing access to the 
communications link, and incoming host-to-host calls from an X.25 network are accepted only if the 
remote host is configured in the local system’s network data base. 


DS/3000 offers the tools to facilitate the sharing of resources within a network. Examples of such 
resources are programs, data structures, or physical hardware elements of the network. You can access 
these resources in any of several modes: 


0 Remote command execution allows you to direct commands to any CPU in the network. 


e 


Remote File Access (RFA) permits the application of processing power to files and devices remote 
from the CPU. RFA also provides the means for extending Interprocess Communications (IPC) across 
a DS link. 


e Program-to-program (PTOP) communication permits direct communications between master and 
Slave programs, each resident in its own CPU within the network. 


© Remote Data Base Access (RDBA) gives the capability for direct and indirect access of data bases on 

‘ry HP 3000 computer in the network. Combining the distributed processing capability of DS/3000 

“th the use of data management subsystems such as VPLUS/3000, KSAM/3000, and PuckOIMACe 
riakes possible the sharing of data 


e Network File Transfer (NFT) is a more efficient mechanism than FCOPY for transferring disc files 
across a communications link. 


The chief advantages of Program-to-Program (PTOP) communication are coprocessing capabilities and 
control of data transmission blocking. Coprocessing master-slave programs execute in multiple systems. 
Program-to-Program communication allows decision making to be distributed within the master-slave 
relationship. The exchange of data and control information between the executing programs can be used 
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to alter program flow to adjust to current conditions in the network. Coprocessing capabilities assume 
importance in networks where synchronization of modifications to related data structures is important 





There exist limitations on certain PTOP application designs. If your PTOP application intends to have one 
master program and multiple slave programs, the SYSTEM BREAK key should be disabled by calling the 
following procedure at the beginning of the master program: 


PROCEDURE DISABLE BREAK; 
BEGIN 
INTEGER STDIN; (file number) 
LOGICAL ANYINFO;(required by fcontrol) 
STDIN: =FOPEN( ,%244); 
FCONTROL(STDIN,14,ANYINFO);(disable system breat, 
END 


If you opt to keep the SYSTEM BREAK key feature, the master program should be structured so that it will 
be made up of one father process and multiple son processes. Each of the son prwvesses will be a master 
PTOP process and communicate with a slave PTOP process on a separate remote system. See Figure 8-1. 
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FATHER 


SON 1 = SON N = 
MASTER PTOP PROCESS MASTER PTOP PROCESS 





SLAVE PTOP PROCESS 
QN REMOTE SYSTEM N 






SLAVE PTOP PROCESS 
QN REMOTE SYSTEM 1 





Figure 8-1. Master Program Structure. 


Blocking control can be utilized in such a manner as to decrease the number of transmissions to move a 
specific amount of data. Since transmission time on a high-speed link is a negligible factor in 
communications performance, the required number of transmissions is the key to performance. Reducing 
the number of transmissions correspondingly reduces the number of line turnarounds. This may become a 
significant performance factor in half-duplex networks or satellite communication links where 
propagation delay affects response time. 
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TRANSMISSIONS BETWEEN SYSTEMS 


Underlying all modes of utilizing DS/3000 is the transmission of data from one system to another. Now 
compare the building of these transmission units for remote file access and for PTOP. 


DS/3000 is supported on three controllers: the Intelligent Network Processor (INP), the Hardwired Serial 
Interface (HSI), and the Synchronous Single-Line Controller (SSJ.C). To configure any of these devices 
into the system, you must specify a buffer length. The buffer length value that you specify represents the 
maximum number of words to be transmitted between systems in one itansmission and it is the system’s 
default buffer size. When you activate DS/3000 with a :DSLINE command, a Zinebuf parameter may 
be specified to override the configured buffer size. Only the first user to activate the line may use 
Linebuf to alter the data communication buffer size. This buffer size may not be respecified until all 
concurrent DS/3000 users have closed their links. In this way, the pertinent buffer limiting factors for 
inter-CPU transmissions are set. . 


How is Linebuf utilized in accessing remote files and remote peripheral devices? The basic unit for file 
system operations is the record (or block of recurds). In remote file access and remote command execution, 
file system blocking limits the transmission unit to a single record or sequential multiple records. File 
system’s FREAD is satisfied by moving a logical record from a file to the user’s buffer. An FREAD on a file 
open with multi-record access is satisfied by a byte count that can be specified to be block-sized. Thus, 
an FREAD on a remote file will pack Linebuf with a record or a specified byte count of sequential 
records. 


Contrast this record-orientation to the array-orientation of PTOP communications. PTOP’s PREAD is 
satisfied by the transmission between programs of the contents of a user-defined buffer. The PTOP 
programmer must construct the buffer by packing it with array(s), record(s), or fields of records. The 
records in one transmission need not even come from the same file. 


In addition to transmitting specified data, DS/3000 attaches a header of varying lengths. The header 
always contains eight words transmitted in a fixed format and can contain additional words in an 
appendage area. For remote command execution and remote file and peripheral device access, the data 
field is usually preceded by a header of 14 words. Some intrinsics, such as FREAD (multirecord), require a 
longer header to convey all parameter information. The header for PTOP communications includes the 
20-word tag field in the appendage; thus the typical PTOP header is 34 words long. The ideal Linebuf 
size will allow the user’s data field plus DS/3000 header information to fit into Linebuf. 
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To illustrate: Assume that you want to read six 80-byte records from a remote file and have specifed a 
Linebuf of 304 words. 


a. If the remote file is defined as REC=-80,1,F, then Remote File Access must retrieve a block of one 
record from the disc, FREAD one record, and transmit one record. The complete data transfer 
requires six disc accesses, six FREADs, and six data transmissions 


b. If the remote file is defined as REC=-80,6,F, then Remote File Access must access the disc to 
retrieve a block of six records, satisfy an FREAD with one record, and transmit one record. The 
complete transfer requires one disc access, six FREADs, and six data transmissions. 


c. If the remote file is defined as REC=-80,6,F, and opene! with the NOBUF and multirecord option, 
then Remote File Access must access the disc to retrieve a block of six records, satisfy an FREAD of 
480 bytes with six records, and transmit the six records. The complete data transfer requires one disc 
access, one FREAD, and one data transmission. 


d. In PTOP, the master program can issue a PREAD. The slave program can pack the buffer with all six 
records, utilizing any of the above three methods. Note that a Linebuf of 304 words is ample to 
permit transmission of 480 bytes (240 words) of data plus 34 words of DS/3000 header information 
in one transmission. 


COORDINATING MASTER AND SLAVE PROGRAMS 


PTOP communication programming requires synchronizing two separate programs at specific points in 
time. For this reason, it is often helpful to block diagram the transmissions and their contents on a 
simulated time line. 


Where the PTOP programmer wants to loop on certain PTOP operations, the loop’s terminating condition 
must, of course, be defined. The master program has direct control over the interprogram 
communications and can terminate a loop under conditions defined locally. More difficult are the 
situations when the slave must communicate to the master that the terminating condition has been met. 
To do this, the slave might send a REJECT response. A REJECT does not allow transmission of data, and so 
requires a terminating exchange of transmissions after all data has been transmitted. 


Another method is to utilize the 20-word itag field (the itag parameter) of the PTOP intrinsics. This 


field is not accessible by the slave unless designated as a parameter in the corresponding master’s PTOP 
operation. For example: 


Master Program Slave Program 
Example A. PREAD(dsnum, target, tcount); GET(itag); 
Example B. PREAD(dsnum, target, tcount, itag);  GET(itag); 


In example A, PREAD does not utilize the itag field. The slave program cannot access itag on this 
transaction. The second PREAD (Example B) might not even initialize the ttag array, but the array has 
been specified as a parameter. The slave program can now return control information to the master via 
this field. The master program logic can inspect ttag and take corresponding action. 


A PCONTROL from the master will also cause an exchange of zitag fields and may be used for passing 


control information. This intrinsic will not pass a data field, however. 
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The control information passed between programs may terminate a loop, may branch to another part of 
the program, may transmit an index to be used in a CASE statement, or may serve any other purpose the 
programmer desires. 


It is important to bear in mind the accessibility of transmitted data When the master program PWRITEsS, 
the slave program cannot process the received data until the ACCEF'T intrinsic has moved the data into the 
slave process stack. The slave program can, however, examine the ttag array before doing the ACCEPT or 
REJECT. After examining the ztag, the slave can then alter the ztag array. The ACCEPT or REJECT 
will transmit the slave’s ttag to the master. Slave local processing can then proceed. 


INTERPROCESS COMMUNICATION AND PTOP 


Interprocess Communication (IPC) is a capability of the MPE tile system that is very beneficial in the 
DS/3000 environment. For some applications, IPC may be easier to implement’ than 
Program-to-Program Communications (PTOP) and may provide other advantages as well. A_ basic 
description of the use of IPC and the changes made to the file system is included in the MPE Intrinsics 
Reference Manual and the MPE File System Reference Manual. 


Message Files 


Message files are used by IPC to transfer requests from one process to another. Each message file is a 
queue, with records acted upon in the order received. Message files are opened with FOPEN, read with 
FREAD, written to with FWRITE, and closed with FCLOSE. 


When a message file is opened, the file system assigns a unique 16-bit ID number to the process that opens 
the file. Each record the process writes to the message file is associated with this number. When the 
writer closes the file, the ID number no longer applies, and may be reused. 


When the files are opened with FOPEN, the user process accesses the file as either a reader or a writer; 
readers access the top of the message file, while writers access the tail. Readers access the file with 
FREAD. The record is copied to the reader, and is deleted from the message queue. Writers access the file 
with FWRITE. FWRITE appends one record to the tail of a message file. See Figure 8-2. 
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FREAD to 
read process 





message | 





message 2 









message 3 


FWRITE from write process 


Figure 8-2. Reading and Writing to a Message File. 









Message files can be created using the : BUILD command or the FOPEN intrinsic. 


Example 


A simple example of the use of IPC for communication between two remote sessions is presented in Figure 
8-3. User Bill establishes a local session on Node A and a remote session on Node B. His application, 
called BILLPROG, opens a local MSGFILE as a reader and a remote MSGFILE as a writer. Then, user Jack 
establishes a local session on Node B and a remote session on Node A. Jack’s application, called JACKPROG, 
opens a local MSGFILE as a reader and a remote MSGFILE as a writer. Now these two unrelated processes 
can communicate with each other through the IPC capability. 
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Figure 8-3. Two-node IPC Communication 


If PTOP had been used in the example in Figure 8-3, a PTOP master program would need to be executing 
in one node and a slave program would have been initiated by the master in the other node. The 
master-slave programs would also require coordination because of their relationship. 


The advantage of IPC becomes more dramatic when two or more processes desire to communicate with 
each other, or when the network is more complex than two nodes. Figure 8-4 shows a network consisting 
of three nodes and a solution that seems very useful in the general DS/3000 applications environment. 
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Figure 8-4. Three-node IPC Communication 





In Figure 8-4, a general application program called a Message Switching Procedure (MSP) is written and 
executed on each node. The MSP performs the following functions: 


Opens a local message file as a reader. 


@ Opens any local applications message files as a writer. 


Opens all DS lines to adjacent nodes. 


Establishes a remote session on each of these nodes. 


Opens a message file on each adjacent node as a writer to be used for communication with each 
adjacent MSP. 


The MSP handles all outgoing requests by forwarding them to the MSP programs on adjacent nodes. The 
MSP also handles all incoming requests by routing them to a local application program or by passing them 
on to the next node in the network. 
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If the network is complex and it is desirable to shift the resteustim tity for routing from the user to the 
MSP, a solution might include addressing within the uses’s data !.ffer and the use of a directory file in 
conjunction with the MSP. The MSP would then use the directory file to determine to what node it 
should forward the message. A more advanced directory file could provide alternate routes in case of 
downed lines. If alternate routes were not available, the unserviceable requests could be stored in a disc 
tile and then be rewritten to the MSP’s MSGFILE when the downed ‘nes are restored. 


In a simple network, it may not be desirable to design an MSP; but it is still possible that using IPC may be 
more advantageous than using PTOP. In this case, each user application could set up one or more remote 
sessions on the appropriate node(s) and communicate with other processes using the normal file intrinsics 
(FOPEN, FREAD, FWRITE, and FCLOSE) and message files. Also, by using the :FILE command, it can be 
transparent to the user or to the application program that the MSGFILFE is located on a remote node. 


The advantage of using an MSP is that several users on a system can communicate with a number of 
remote processes, but only one remote session is required per node. Since fewer remote sessions are 
necessary, the amount of memory required is decreased. 


The major advantage of IPC versus PTOP is that there is no limitation to the number of local or remote 
processes with which a single process can communicate. The processes are fully bilateral with IPC making 
it easier to implement and expand the application for more complex networks. Also, activities such as 
development, testing, and debugging can all be done on one node, and then the resulting application can be 
distributed. 


DEBUGGING 


Where the amount of local processing in a PTOP application is significant, it may be helpful to debug the 
master and slave programs as local programs. MOVEs on dummy arrays or FREADs on dummy files can be 
substituted for communication operations to simplify debugging of the local processing. 


When the time arrives to run the programs in master-slave fashion, a :RUN PROG;DEBUG is sufficient to 
invoke the Debug Utility for the master. This will not, however, allow the programmer to set a 
break-point in the slave program or to examine the slave process stack. To facilitate debugging a slave 
program, the first executable statement of the slave program should be the DEBUG intrinsic. 


LINE BUFFERS/CONTINUATION BUFFERS 


DS/3000 is designed to send across the line, in a single transfer operation, the amount of data configured 
as the PREFERRED BUFFER SIZE for the line controller (INP, SSLC, or HSI). The first person to use a DS 
line can override the configured line buffer size by specifying a different value with the linebuf 
parameter of a :DSLINE command. 


When a user specifies Linebuf=xxxx, the xxxx value tells the Communication Subsystem (CS/3000) the 
maximum amount of data DS/3000 will ever send across the line in a single request. For example, if you 
say Linebuf=1074, you are saying the largest buffer DS/3000 can pass to the Communication Subsystem 
is 1074 words. 


The 1074 words will always consist of both user data and DS/3000 fixed header and variable-length 
appendage characters. The additional characters (approximately 20 to 50 words) give to and from 
information, intrinsic names, etc., and vary for RFA and PTOP operations. 
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When a DS/3000 user requests the transfer of more data in a single operation than the line buffer can 
accomodate, DS/3000 automatically fills the line buffer, CS/3000 makes the transfer, then DS/3000 
refills it, and transfers again -- until all of the user’s data has been sent. When a user’s single request 
causes DS/3000 to make several transfer operations. the additional buffers of data are known as 
“continuation buffers." As stated before, the idea] line buffer should be large enough to eliminate the 
need for continuation buffers. 
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COMPRESSION 


Compression of data on the communications link may be specified in order to achieve higher throughput. 
DS/3000 initialization procedures allow compression only if both systems are capable of performing 
compression. Compression is handled on an individual basis, so that on a non-exclusive line, some users 
will compress while others will not. 


Compression is most helpful in applications using line speeds up tu 56K bps. It is generally neither 
helpful nor desirable in applications that use higher data rates. It can be specified by the user in three 
different ways: 


e At generation time by use of SUBTYPE=1 while configuring IODSO or IODS> (refer to Section 1 in 
the DS/3000 HP 3000 to HP 3000 Network Administrator Manual. This configured subtype sets the 
default for the line. 


© While executing the :DSCONTROL console command. A console operator uses the parameter to 
override the con: gured line default or to reset to the coutigured state. 


@ While executing a :DSLINE command in a session or job. Use of the :DSLINE parameter allows 
individual users to control whether or not their data will be compressed, and will override the current 
line default. 


Compression generally increases throughput by reducing redundancy in the data, which results in a 
reduction in the number of characters being transmitted over the communications link. The compression 
technique compresses any occurance of three or more consecutive characters. Compression does not take 
place in the data only. It can occur in the fixed part or the appendage of the DS/3000 header. 


The amount of redundancy in data or files may vary significantly. Source or listing files may be 
compressed by as much as 75 percent, but a more typical random assortment of HP 3000 files may be 
reduced by an amount closer to 25 percent. Obviously, the actual reduction will vary from application to 
application. Comparative tests with and without compression will indicate the benefits. 


In some cases, however, compression could actually result in an increase in the number of characters to be 
transmitted. For this reason, DS/3000 examines each case when compression is specified. If a situation is 
found where compression would be detrimental to performance, DS/3000 sends the data uncompressed. 


Using compression and decompression increases the system overhead at both ends of the link. The decision 
on whether to use compression depends on the communications link data rate, system load, and the 
amount of redundancy in the data being transmitted. Often, a test of relative throughput with normal 
system load and "typical" data will provide an indication of the benefits of using compression. 
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Formats for Inserted Compression Characters 


Octal Value Meaning 
XX nnn nnn XX = compression type 
0O = uncompressed character string 
10 = repeated blanks 
11 =repeated non-blank characters 
(next byte is the ASCII value for the repeated character) 


nnn nnn = octal character count 


1 to 77. 
Examples: 
036 36 (octal) non-compressed characters 
217 17 (octal) blank characters 
323.052 23 (octal) compressed * characters 


For example, sending the string 1111111111 uncompressed resulted in the following string: 
031.061 031.061 031.061 031.061 031.061 

Sending the string compressed resulted in the following string: 
312.061 


where the 3 shows that there is a repeated non-blank character, the 12 means 12 octal (10 decimal) 
characters, and the 061 is the ASCII representation of 1. 


PERFORMANCE 


The performance achieved while using the DS/3000 link may vary widely, and it depends on many 
factors. 


Computer System Dependent 


The activity mix on the respective HP 30('9 will affect performance. It depends upon the character of 
the simultaneous activity: such as the number of jobs, number of CPU-bound jobs and their relative 
priority, contention for disc, memory size and amount of swapping, quantum size, etc. 


Communication Links 


The choice of the communications link will provide an upper limit to the performance. Generally, a 
full-duplex line will outperform a half-duplex line by reducing line turnaround delays. A half-duplex 
line with a smaller request-to-send/clear-to-send delay will be faster (such as a 208B at 50 milliseconds 
versus a 208B at 150 milliseconds). 
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Line quality can result in wide variations in performance at times when line errors are high. A leased 
line 1s generally better and more predictable than a dial-up imme. Some telephone offices provide cleaner 
lines depending on the age and nature of their switching gear. 


Applications 


For a given amount of data, the buffer size selected will affect performance. The smaller the number of 
requests required to transmit a given quantity of data, the higher the throughput. This also includes 
continuation requests. The data may be packed into larger buffers while using PTOP applications. The 
data may also be blocked into larger records for RFA applications. (RFA and FCOPY handle one record 
at a time, even though the file may use blocking) 


As described earlier, use an appropriate line buffer size. Use a line buffer large enough to contain the full 
record or buffer, plus the DS/3000 fixed blocks and appendage header words. (The "rule-of-thumb" is 50 
words larger than the data size.) 


For applications to be run on dial-up lines, the line errors normally suggest a reasonable Linebuf 
maximum of 1024 words. Analysis of :SHOWCOM xx ;ERRORS output and trace listings for error rates 
will allow modification of this recommendation for "typical" conditions. (This suggested maximum value 
of 1024 could be either increased or decreased when an SS] "" ts beiny used; but the value could only be 
decreased when the communications interface is an INP, suuce the maximum buffer size for the INP is 
1024 words.) 


PTOP applications allow both the master and slave programs to do a larger share of data searching, 
qualification, and manipulation at each local computer, thus reducing the quantity of data which must be 
sent across the line. 


Remote Listing 


Where data must be sent to a remote device (such as a line printer or a magnetic tape) it may be possible 
to send the program that generates the data to the remote computer for execution. For example, since a 
compiler listing can be quite large, 1t might be more efficient to transmit the source across the line and do 
a remote compilation and remote list, rather than doing a remote list for a local compilation. 
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MULTIPLE REMOTE ACCESS 


While presenting the basic concepts of DS/3000 in the tutorial sections of this manual, the examples were 
intentionally limited to simple networks. From those somewhat simplistic illustrations, it might appear as 
though the only way your local computer can talk to more than one other computer 1s through additional 
parallel communication lines from your local system to the additional remote systems. Actually, it is 
possible to communicate with other remote computers in the network that have no direct connection with 
your local computer. This communication is made possible by going through one remote computer (to 
which you do have a direct communication line) to reach another remote computer to which the first 
remote computer is connected. To reach a second remote system through a first remote system, a multiple 
REMOTE command is used. The syntax 1s as follows: 


sREMOTE [xxx] [REMOTE [xxxr]] ... [eommand] 


In this way, the local user can initiate a session sequentially on each remote system. See Figure 8-5. 


SYSTEM SYSTEM SYSTEM SYSTEM 
A B Cc D 


‘REMOTE LISTF............. Lists these 
filas to 
system A 
TFREMOTE REMOTE LISTF............00.0.0..0202.. Lists these 
files to 
System A 


-REMOTE REMOTE REMOTE LISTF 


i eats aden ah aes cecid ase es ee Beds oe oath ap Notte Lists these 
files to 
System A 


Figure 8-5. Multiple Remote Accessing Example 


Figure 8-5 shows how your local system (System A) can obtain a list of the files in the first remote system 
(System B) by issuing the command: 


:REMOTE LISTF 
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To obtain a similar list of files from System C in this kind of network (where the communications link 1s 
through an intermediate remote computer), use the command: 





>REMOTE REMOTE LISTF 


Likewise, you can route your request through to System D by expanding the command to: 


>REMOTE REMOTE REMOTE LISTF 


Using this compound command accomplishes the same result as if you had issued the following series of 
separate commands: 


:REMOTE 
#REMOTE 
#REMOTE 
#LISTF 














There is an important difference in the way of returning to your local system, however. When you reach 
System D (Figure 8-4) by entering the compound command 


:REMOTE REMOTE REMOTE 
# 


the ¥ prompt is coming from the Command Interpreter (CI) on System D. If you now type a colon (:) 


#: 


you are being switched back to your local CI (System A). But if you were to use the alternative method of _ . 
reaching System D with a series of separate commands 


:REMOTE 
#REMOTE 
#REMOTE 
# 








and then you typed a colon as before, you would be switched to System C. To get back to your local 


system (System A), you must return a step at a time (just as you went out to System D a step at a time) as 
follows: 


> REMOTE 
#REMOTE 
#REMOTE 
fe 

# 

#: 








Jee 
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SECTION 


Before establishing a DS/3000 communications link, the console : DSCONTROL command must be used 
to OPEN a line, so that it is available to DS/3000 users. The : DSCONTROL command allows you to 
enable or disable the DS/3000 subsystem on a specific communications link. 


DSCONTROL CONSOLE COMMAND 





For easy reference, this command 1s shown in the following format: 


e SYNTAX Shows the format of the command. 
e PARAMETERS Describes the variables in the command. 
e OPERATION Describes the command in detail. 

“= e EXAMPLES Shows the command in use. 








:DSCONTROL 


SYNTAX 


:DSCONTROL dsdevice [function [... function]] 


where the parameter function has the following options: 


[;CANCEL] 


OPEN [,MASTER 
; SHUT herd | [SPEED=]speed | | 


grey Se ue TE ge ge tee 


ALL] [mask] [,numentries] [WRAP] [, filename] \ | 


Bee IS 


,ON [ 
; TRACE go 


;COMP 
> NOCOMP 


count 


| 
| 
F-3r4 
| 
| 


sreray=d Dey aT) | 


PARAMETERS 

dsdevice The logical device number or the device class name of the 
DS/3000 communications device (IODSO or IODSX). On your 
system’s I/O configuration listing, the device is back referenced by 
a pound sign (#) to a previously defined INP, HSI, or SSLC. 
(Required parameter.) 

OPEN Makes the line available for remote communication via the 


DS/3000 Subsystem. For bisync DS/3000 (IODSO), the DS 
subsystem is enabled, but no activity is initiated on the 
communications link. For DS/3000-X.25 (IODSX), the DS 


paw 

















CANCEL 


SHUT 


MASTER 


SLAVE 


Linespeed 


:DSCONTROL 


subsystem establishes a communications link with the PDN. 
(Required parameter.) 


Applicable only to X.21. Cancels all queued outgoing call 
requests. Sends an abort request to the communications device. 
Validates that the device is X.21 related and that there is a 
queued request. CANCEL is executed before any other 

: DSCONTROL parameter. 


Initiates an orderly line shutdown. Refer to OPERATION for 


details about the line closing procedure. 


Limits DS/3000 line activity to outgoing requests only. No 
incoming sessions are allowed. 


Limits DS/3000 line activity to incoming requests only; no 
outgoing activity is allowed. 
Default: Both MASTER and SLAVE processing are allowed. 
Transmission rate in characters per second (Bit Rate/8). This 
parameter is effective only if your system generation for the line 
selected SPEED CHANGEABLE. Specify Ztnespeed if yours isa 
European installation with modems running at half speed, or if 
the line is hardwired and you want to override the configured 
default. It may be necessary to include this parameter if the 
length of cables used for HSI communications has been changed 
since the system was configured. 
HSI speed: 250 000 (cable lengths less than 1000 ft.) 

125 000 (cable lengths greater than 1000 ft.) 
INP or SSLC speed: 250, 300, 600, or 1200 
INP only speed: 2400 or 7200 
The SPEED= keyword in the open option may be omitted from a 
: DSCONTROL command. For example, the following two 
commands have exactly the same effect: 
:DSCONTROL 60;OPEN,MASTER,SPEED=250000 
:DSCONTROL 60;OPEN,MASTER,250000 


Remember, both ends of the line must operate at the same speed. 


Default: System configuration values. 
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TRACE ,ON 


ALL 


mask 


numentries 
WRAP 
filename 


TRACE, OFF 
COMP 


NOCOMP 


MON »DS 
»CS 


Activates the TRACE facility to provide a record of 
communications activities. Trace parameters are positional. The 
line must already be open, or the OPEN keyword must also be 
included (to open the line). 


Generates trace records for all line activity. 

Default: Records are written only for transmission errors. 

An octal number preceded by a percent sign (%nn). Used to select 
type of trace entries generated. Refer to Sections 3 and 4 in the 
DS/ 3000 Network Administrator's Manual for an explanation of 
the mask bits. 

Default: %37 (all except PSTN). 

Decimal integer for the maximum number of entries in a trace 
record, not greater than 248. 

Default: 24. (See OPERATION.) 

Trace entries that overflow the trace record overlay the prior 
trace record entries. 


Default: Overflow entries are discarded. 


A name for the trace file. 


Default: DSTRCxxx.PUB.SYS (where xxx is the LDEV of the 
dsdevice). 


Deactivates the TRACE facility, so that no records are kept of 
DS/3000 actions, states, and events. Also closes the trace file. 


Sets data compression as the default mode of operation for all line 
users. The line need not be open to use COMP. 


Sets uncompressed data as the default mode of operation for all 
line users. The line need not be open to use NOCOMP. 


Activates internal communication monitoring activity to give 
additional information on a subsequent cold dump of the system. 
The line must be open for the use of MON. 
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MON Requests monitoring of all levels of activity. 


MON ,DS Requests monitoring at the DS/3000 level of 
internal software operation. 


MON ,CS Requests monitoring at the Communication System 
level of internal software operation. 


Default: No monitoring. 


Used only for system troubleshooting. 


MOFF Deactivates internal DS/3000 monitor records. Line must be 
open for the use of MOFF. 


RETRY=| DEFAULT Changes the communications error retry count to the specified 
count value. The retry counter controls the number of times the system 
attempts to send or receive a message across the communications 
link. 
DEFAULT Specifies a limit of 15 retries after a line error 
occurs. 

count Can be any value within the range of 0 to 255. 
Default: 15. 

OPERATION 


Unless : DSCONTROL is issued from the master console, this command requires the user to have CS and 
ND capability. In addition, all users except the console operator are granted access to :DSCONTROL 
only if they are ALLOWed to use the command and are ASSOCIATEd with the specified DS device. 


Only one DS/3000 communications device can be active (OPEN) on a controller at any given time. 
Once opened (with the : DSCONTROL command), a communications link can be shared by multiple 
DS/3000 users. It cannot, however, be shared by users of other communications subsystems supported 
by your system (for example, DSN/MRJE). Thus, you must SHUT the DS/3000 communications device 
before the controller can be opened for use by another subsystem. 


Before issuing a :DSCONTROL command, use the : SHOWDEV command to check whether a 
communications link is already established. The LDEV for the INP, SSLC, or HSI port will be 
UNAVAI Lable if the communications link is in use by any subsystem; the LDEV for a DS/3000 
communication device, driver IODSO or IODSX, will be AVAILable if it is currently OPEN for use by 
DS/3000 users. 


If a DS device class includes more than one DS device, the functions specified in the : DSCONTROL 
command apply to all devices in that class. If you have not been ALLOWed to use this command, you 
can only control those devices in the device class with which you have been ASSOCIATEd (if any). 
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If you include more than one function in a :DSCONTROL command, each function (with its 
subparameter list) must be separated by a semicolon. A function that duplicates or conflicts with a 
previous function overrides that function. Functions can appear in any order but are executed in the 
following order: 


1. CANCEL 

2. OPEN/SHUT 

3. TRACE 

4. MON/MOFF 

5. COMP/NOCOMP 

The default name of the trace file is: 

DSTRCxxx. PUB.SYS 

where xxx is the logical device number of the dsdevice. 


If no trace file exists when you turn on the trace facility and you do not specify numentries, the 
system creates a file to hold 24 entries in each record. 


When using the bisync protocol, the SHUT parameter initiates an orderly line closing procedure. If no 
sessions or applications are using the line when you shut it, line disconnection occurs immediately. If 
any user (including applications) has the line open, the line remains connected until all sessions and 
applications CLOSE the line, or until those accessing the line terminate or are aborted. Once CLOSEd 
by the console operator, no new users may access the line until the operator reopens it. When using 
the X.25 capability of DS/3000, the SHUT parameter disconnects the line immediately, even if there 


are current users on the line. 
NOTE 


Occasionally you may not be able to SHUT a standard 
(non-X.25) DS line. This could happen, for example, if a 
DS user forgot to issue a :DSLINE xxx;CLOSE 
command but still has a local session. It could also 
happen if a remote session is "hung." In such a situation, 
you can "kill" all activity across the line by issuing an 
:ABORTIO xxx (where xxx is the logical device number 
of the dsdevice). Following the use of the : ABORTIO 
xxx command, a second :DSCONTROL xxx 3SHUT 
command will complete successfully. 


9-6 














(DSCONTROL 


EXAMPLES 





To open X.25 line number 55, thereby making it available for use by DS/3000 users, enter: 

:DSCONTROL 55;OPEN 

To permit the local HP 3000 to process only master (outgoing) requests on DS line number 55, enter: 

:DSCONTROL 55;OPEN,MASTER 

To activate the CS Trace facility for DS line 55 (the line is already open), enter: 

:DSCONTROL 55; TRACE ,ON,ALL 

To open X.25 line 55 and activate CS Trace with a maximum of 250 entries in a trace record, enter: 
o~ :DSCONTROL 55;OPEN;TRACE,ON,,,250 


To open the line named REMSYS and establish compression as a default and enable internal monitoring, 
enter: 


:DSCONTROL REMSYS;OPEN ;COMP;MON 
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APPENDIX 


The following is a summary of the error code numbers and messages that may be encountered. The 
messages, as listed here, have been grouped into several categories. For example, the first group 
contains all messages pertaining to :DSLINE syntax problems, while the second group contains the 
messages that report a DS/3000 functional problem. Each group is identified with an explanatory 
heading, and the messages are listed in numerical sequence within each category for easy reference. 


ERROR CODES AND MESSAGES 





:DSLINE SYNTAX ERRORS 


These messages are sent to the terminal user to point out an error in syntax or to warn of the 
consequences of a request. 

1300 REMOTE JOBS ARE NOT ALLOWED !. (CIERR 1300) 

1301 DSLINE CANNOT CONTAIN BOTH OPEN AND CLOSE. (CIERR 1301) 

1302 DSLINE REQUIRES AT LEAST ONE PARAMETER. (CIERR 1302) 


1303 DSNUMBER SPECIFICATION MUST BE A NUMBER FROM 1 THRU 255. 
(CIERR 1303) 


1304 DSLINE #1! DOES NOT IDENTIFY AN OPEN DS LINE. (CIERR 1304) 


1305 EXPECTED LINEBUF, PHNUM, IOCID, REMID, OPEN, CLOSE, 
QUIET, COMP, NOCOMP, OR EXCLUSIVE. (CIERR 1305) 


1306 MULTIPLE USE OF ! IS NOT ALLOWED. (CIERR 1306) 


1307 THE SYNTAX FOR ! REQUIRES AN = SIGN FOLLOWED BY DATA. 
(CIERR 1307) 


1308 PHNUM IS 1 TO 20 DIGITS AND DASHES. (CIERR 1308) 
1309 ! LIST CAN CONTAIN ONLY ONE ELEMENT. (CIERR 1309) 
1310 THE SPECIFIED LOGICAL DEVICE IS NOT OPEN. (CIERR 1310) 


1311 THE FIRST CHARACTER OF AN ID SEQUENCE MUST BE A " OR A ( 
(CIERR 1311) 


1312 THE ID SEQUENCE MUST TERMINATE WITH A ). (CIERR 1312) 
1313 THE ID SEQUENCE MUST TERMINATE WITH A“. (CIERR 1313) 


1314 A NUMERIC ID SEQUENCE ELEMENT MUST BE 1 THRU 255 (OR 
#377). (CIERR 1314) 


Error Codes and Messages 

1315 LINEBUF MUST BE A NUMERIC VALUE FROM 304 THRU 4096. 
(CIERR 1315) 

1316 UNABLE TO COMPLETE THE REMOTE COMMAND. (CIERR 1316) 

1317 NOT A CURRENTLY AVAILABLE DSLINE. (CIERR 1317) 


1318 USE OF EXCLUSIVE REQUIRES BOTH NS AND CS CAPABILITY. 
(CIERR 1318) 


1319 THE DS LINE #L! IS IN USE BY A PROGRAM OR SUBSYSTEM AND 
CANNOT BE CLOSED. (CIERR 1319) 


1320 EXPECTED A RESPONSE OF YES, Y, NO, OR N. (CIERR 1320) 
1321 UNABLE TO OPEN THE DS LINE ON DEVICE !. (CIERR 1321) 
1322 @ IS INVALID IN THIS CONTEXT. (CIERR 1322) 


1323 A DSLINE OPEN REQUIRES A VALID DS DEVICE NAME AS THE 
FIRST PARAMETER. (CIERR 1323) 


1324 FROM ADDRESS MUST BE BETWEEN 1 AND 14 CHARACTERS INCLUSIVE. 
(CIERR 1324) 


1325 TO ADDRESS MUST BE BETWEEN 1 AND 14 CHARACTERS INCLUSIVE. 
(CIERR 1325) 


1326 FROM AND TO ADDRESS MUST BE A DECIMAL NUMBER. (CIERR 1326) 


-1389 INVALID OR MISSING DELIMETER FOR SELECTION SIGNAL SEQUENCE. 
(CIERR 1389) : 


1390 SELECTION SIGNAL SEQUENCE MUST BE FROM 1 TO 30 CHARACTERS. 
(CIERR 1390) 


1391 BOTH QUEUE AND NOQUEUE SPECIFIED; NOQUEUE USED. (CIWARN 1391) 


1392 ONLY ! WORDS WERE ALLOCATED FOR THE LINE BUFFER. 
(CIWARN 1392) 


1393 COMPRESSION REQUEST NOT HONORED. REMOTE DOES NOT SUPPORT 
THIS FEATURE. (CIWARN 1393) 


1394 COMPRESSION PARAMETER RESPECIFIES AND OVERRIDES PREVIOUS 
COMPRESSION PARAMETER. (CIWARN 1394) 


1395 OPEN PARAMETERS ENTERED ON A CLOSE REQUEST ARE IGNORED 
(CIERR 1395) 


1396 AN ID LIST MUST CONTAIN 255 OR LESS ELEMENTS. 
(CIWARN 1396) 


1397 AN UNNECESSARY DELIMITER IS IGNORED. (CIWARN 1397) 
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1398 THERE ARE NO DS LINES OPEN. (CIWARN 1398) 


1399 MULTIPLE USE OF ! IS REDUNDANT AND IGNORED. (CIWARN 1399) 


DS/3000 FUNCTIONAL ERRORS 


These messages report a functional problem within the system. 


201 


202 


203 


204 


205 


206 


207 


208 


209 


210 


211 


212 


213 


214 


REMOTE DID NOT RESPOND WITH THE CORRECT REMOTE ID. 
(DSERR 201) 


SPECIFIED PHONE NUMBER IS INVALID. (DSERR 202) 
REMOTE ABORT/RESUME NOT VALID WHEN DOING PROGRAM-TO- 
PROGRAM COMMUNICATION. USE LOCAL ABORT/RESUME. 
(DSWARN 203) 


UNABLE TO ALLOCATE AN EXTRA DATA SEGMENT FOR DS/3000. 
(DSERR 204) 


UNABLE TO EXPAND THE DS/3000 EXTRA DATA SEGMENT. 
(DSERR 205) 


SLAVE PTOP FUNCTION ISSUED FROM A MASTER PROGRAM. 
(DSERR 206) 


SLAVE PTOP FUNCTION OUT OF SEQUENCE. (DSERR 207) 


MASTER PTOP FUNCTION ISSUED BY A SLAVE PROGRAM. 
(DSERR 208) 


SLAVE PROGRAM DOES NOT EXIST OR IS NOT PROGRAM FILE. 
(DSERR 209) 
Creation of Slave Program failed, possibly because of invalid stack size. 


WARNING -- INVALID MAXDATA OR DLSIZE FOR A SLAVE PROGRAM. 
SYSTEM DEFAULTS ARE IN EFFECT. (DSWARN 210) 


SLAVE ISSUED A REJECT TO A MASTER PTOP OPERATION. 
(DSWARN 211) 


FILE NUMBER FROM IOWAIT NOT A DS LINE NUMBER. (DSWARN 212) 


EXCLUSIVE USE OF A DS LINE REQUIRES BOTH ND AND CS 
CAPABILITY. (DSERR 213) 


THE REQUESTED DS LINE HAS NOT BEEN OPEN WITH A USER :DSLINE 
COMMAND OR A REQUIRED : REMOTE HELLO HAS NOT BEEN DONE. 
(DSERR 214) 
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215 


216 


217 


218 


219 


220 


221 


222 


223 


224 


225 


226 


227 


228 


231 


232 


233 


234 


235 


236 


237 


238 


DSLINE CANNOT BE ISSUED BACK TO THE MASTER COMPUTER. 
(DSERR 215) 


MESSAGE REJECTED BY THE REMOTE COMPUTER. (DSERR 216) 
INSUFFICIENT AMOUNT OF USER STACK AVAILABLE. (DSERR 217) 
INVALID PTOP FUNCTION REQUESTED. (DSERR 218) 


MULTIPLE POPEN. ONLY ONE MASTER PTOP OPERATION CAN BE 
ACTIVE ON A DS LINE. (DSERR 219) 


PROGRAM EXECUTING GET WAS NOT CREATED BY POPEN. (DSERR 220) 
INVALID DS MESSAGE FORMAT. INTERNAL DS ERROR. (DSERR 221) 
MASTER PTOP FUNCTION ISSUED PRIOR TO A POPEN. (DSERR 222) 


REQUEST TO SEND MORE DATA THAN SPECIFIED IN POPEN. 
(DSERR 223) 


FILE EQUATIONS FOR A REMOTE FILE CONSTITUTE A LOOP. 
(DSERR 224) 


CANNOT ISSUE POPEN TO A SLAVE SESSION IN BREAK MODE. 
(DSERR 225) 


SLAVE PROGRAM HAS TERMINATED BEFORE EXECUTING "GET". 
(DSERR 226) 


REMOTE HELLO MUST BE DONE TO INITIATE REMOTE SESSION. 
(DSERR 227) 


EXCEEDED MAXIMUM NUMBER OF VIRTUAL CHANNELS PER JOB. 
(DSERR 228) 


INVALID FACILITY IN CONNECTION REQUEST. (DSERR 231) 

THE REMOTE COMPUTER IS NOT OBTAINABLE. (DSERR 232) 

VIRTUAL CIRCUIT IS NOT AVAILABLE. (DSERR 233) 

QUEUEING IS REQUIRED TO COMPLETE THE REQUEST. (DSERR 234) 
DS MESSAGE SEQUENCING ERROR. (DSERR 235) 

COMMUNICATIONS HARDWARE HAS DETECTED AN ERROR. (DSERR 236) 
CANNOT CURRENTLY GAIN ACCESS TO THE TRACE FILE. (DSERR 237) 


COMMUNICATIONS INTERFACE ERROR. INTERNAL FAILURE. 
(DSERR 238) 





























239 


240 


241 


242 


243 


244 


245 


246 


247 


248 


249 


250 


251 


252 


253 


254 


255 


256 


Error Codes and Messages 


-COMMUNICATIONS INTERFACE ERROR. TRACE MALFUNCTION. 


(DSERR 239) 


LOCAL COMMUNICATION LINE WAS NOT OPENED BY OPERATOR. 
(DSERR 240) 


DS LINE IN USE EXCLUSIVELY OR BY ANOTHER SUBSYSTEM. 
(DSERR 241) 


INTERNAL DS SOFTWARE ERROR ENCOUNTERED. (DSERR 242) 
REMOTE OR PDN IS NOT RESPONDING. (DSERR 243) 


COMMUNICATIONS INTERFACE ERROR. LINE RESET OCCURRED. 
(DSERR 244) 


COMMUNICATIONS INTERFACE ERROR. RECEIVE TIMEOUT. 
(DSERR 245) 


COMMUNICATIONS INTERFACE ERROR. REMOTE DISCONNECTED. 
(DSERR 246) 


COMMUNICATIONS INTERFACE ERROR. LOCAL TIME OUT. (DSERR 247) 


COMMUNICATIONS INTERFACE ERROR. CONNECT TIME OUT. 
(DSERR 248) 


COMMUNICATIONS INTERFACE ERROR. REMOTE REJECTED 
CONNECTION. (DSERR 249) 


COMMUNICATIONS INTERFACE ERROR. CARRIER LOST. (DSERR 250) 


COMMUNICATIONS INTERFACE ERROR. LOCAL DATA SET FOR THE 
DS LINE WENT NOT READY. (DSERR 251) 


COMMUNICATIONS INTERFACE ERROR. HARDWARE FAILURE. 
(DSERR 252) 


COMMUNICATIONS INTERFACE ERROR. NEGATIVE RESPONSE TO THE 
DIAL REQUEST BY THE OPERATOR. (DSERR 253) 


COMMUNICATIONS INTERFACE ERROR. INVALID I/O CONFIGURATION. 
(DSERR 254) 


COMMUNICATIONS INTERFACE ERROR. UNANTICIPATED CONDITION. 
(DSERR 255) 


REQUEST QUEUED BEHIND PREVIOUS REQUEST. 


Error Codes and Messages 


‘DSCONTROL INFORMATORY MESSAGES 


These messages convey status information. 


300 DS 
301 DS 
302 DS 
303 DS 
304 DS 
305 DS 
306 DS 
307 DS 
308 DS 
309 DS 
310 DS 
311 DS 
312 DS 
313 DS 


314 DS 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


DEVICE 


Y; 


t. 
¢ 


MASTER AND SLAVE ACCESS SHUT. 


: SLAVE ACCESS OPENED; MASTER ACCESS SHUT. 
: MASTER ACCESS OPENED; SLAVE ACCESS SHUT. 
: MASTER AND SLAVE ACCESS OPENED. 

: TRACE ACTIVATED USING TRACE FILE !?. 


: TRACE DEACTIVATED. 


MONITORING ACTIVATED. 


MONITORING DEACTIVATED. 


: DEBUG MODE ACTIVATED. 


; DEBUG MODE DEACTIVATED. 


: SPECIAL DEBUG MODE ACTIVATED. 


: DEFAULT MODE IS NO COMPRESSION. 


: DEFAULT MODE IS COMPRESSION. 


RETRY COUNT NOW EQUALS !. 


> CALL REQUEST CANCELED. 


-DSCONTROL ERROR MESSAGES 


These messages point out an error in syntax or warn of the consequences of a request. 


4100 


4101 


4102 


4103 


NUMBER OF PARAMETERS EXCEEDS MAXIMUM OF !?. 


EXPECTED AT LEAST TWO PARAMETERS: 
CLASS/NUMBER AND A FUNCTION KEYWORD. 


USER IS NOT ASSOCIATED WITH DS DEVICE !. 
FUNCTIONS EXECUTED FOR THIS DEVICE. 


(CIERR 4100) 


A DS DEVICE 
(CIERR 4101) 


EXPECTED A DEVICE CLASS NAME OR LOGICAL DEVICE NUMBER FOR 
ONE OR MORE DS DEVICES. 


(CIERR 4102) 


NO CONTROL 
(CIWARN 4103) 
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4104 


4105 


4106 


4107 


4108 


4109 


4110 


4111 


4112 


4113 


4114 


4115 


4116 


4117 


4118 


4119 


4120 


4121 


4122 


4123 


4124 


4125 


Error Codes and Messages 
USER IS NOT ALLOWED TO USE :DSCONTROL AND IS NOT ASSOCIATED 
WITH THE DS DEVICE(S). (CIERR 4104) 


EXPECTED ONE OR MORE OF THE CONTROL FUNCTIONS: OPEN, SHUT, 
MON, MOFF, COMP, NOCOMP, TRACE, OR DEBUG. (CIERR 4105) 


INVALID CONTROL FUNCTION. EXPECTED ONE OF: OPEN, SHUT, 
MON, MOFF, COMP, NOCOMP, TRACE, OR DEBUG. (CIERR 4106) 


MASTER OVERRIDES PREVIOUS MASTER/SLAVE OPTION. 
(CIWARN 4107) 


SLAVE OVERRIDES PREVIOUS MASTER/SLAVE OPTION. 
(CIWARN 4108) 


SPEED OPTION OVERRIDES PREVIOUS SPEED OPTION. 
(CIWARN 4109) 


OPEN OVERRIDES PREVIOUS OPEN/SHUT FUNCTION. (CIWARN 4110) 
SHUT OVERRIDES PREVIOUS OPEN/SHUT FUNCTION. (CIWARN 4111) 
TRACE OVERRIDES PREVIOUS TRACE FUNCTION(S). (CIWARN 4112) 
DEBUG OVERRIDES PREVIOUS DEBUG FUNCTION(S). (CIWARN 4113) 
MON OVERRIDES PREVIOUS MON/MOFF FUNCTION. (CIWARN 4114) 
MOFF OVERRIDES PREVIOUS MON/MOFF FUNCTION. (CIWARN 4115) 
COMP OVERRIDES PREVIOUS COMP/NOCOMP FUNCTION. (CIWARN 4116) 


NOCOMP OVERRIDES PREVIOUS COMP/NOCOMP FUNCTION. 
(CIWARN 4117) 


EXPECTED A "3" , °,° , OR RETURN AS DELIMITER. (CIERR 4118) 
EXPECTED EITHER A ‘";" OR RETURN AS DELIMITER. (CIERR 4119) 
EXPECTED A "=" AS DELIMITER FOR SPEED OPTION. (CIERR 4120) 
EXPECTED A "," AS DELIMITER BETWEEN OPTIONS. (CIERR 4121) 


ILLEGAL OPEN/SHUT OPTION. EXPECTED ONE OF: MASTER, SLAVE, 
SPEED, OR LINESPEED VALUE. (CIERR 4122) 


EXPECTED A POSITIVE DOUBLE VALUE FOR LINESPEED. 
(CIERR 4123) 


CS CAPABILITY REQUIRED TO USE :DSCONTROL. (CIERR 4124) 


PM CAPABILITY REQUIRED TO USE DEBUG FUNCTION. (CIERR 4125) 
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4126 


4127 


4128 


4129 


4130 


4131 


4132 


4133 


9134 


4135 


4136 


4137 


4138 


4139 


4140 


4141 


4142 


4143 


4144 


4145 


4146 


4147 


DEBUG FUNCTION MAY ONLY BE USED BY SYSTEM CONSOLE. 
(CIERR 4126) 


EXPECTED NO OPTION FOR DEBUG OR ONE OF THE FOLLOWING: 
ON, OFF, OR POSITIVE INTEGER VALUE. (CIERR 4127) 


EXPECTED NO OPTION FOR MON/MOFF OR ONE OF THE FOLLOWING: 
CS OR DS. (CIERR 4128) 


COMP/NOCOMP FUNCTIONS HAVE NO OPTIONS. (CIERR 4129) 


SPEED OPTION IGNORED FOR SHUT FUNCTION. (CIWARN 4130) 


EXTRANEOUS ";"' IGNORED. POSSIBLE MISSING FUNCTION? 


(CIWARN 4131) 


EXTRANEOUS “," IGNORED. 
(CIWARN 4132) 


POSSIBLE MISSING OPTION? 


CREATION OF DS MONITOR PROCESS FAILED. (CIERR 4133) 


PROGRAM FILE "DSMON.PUB.SYS" MISSING. (CIERR 4134) 


DS MONITOR UNABLE TO RUN AS A SYSTEM PROCESS. (CIERR 4135) 


CS DEVICE ! IS UNAVAILABLE FOR USE. (CIERR 4136) 


DS DEVICE MUST BE OPEN PRIOR TO USE. (CIERR 4137) 

USER SPECIFIED TRACE FILE NOT ALLOWED WHEN MORE THAN ONE 
DEVICE IN DEVICE CLASS. (CIERR 4138) 

DS DEVICE ! CURRENTLY CONTROLLED ELSEWHERE. (CIWARN 4139) 
DS DEVICE !: OPEN/SHUT NOT EXECUTED DUE TO ABOVE. 

(CIWARN 4140) 
DS DEVICE t: TRACE NOT EXECUTED DUE TO ABOVE. (CIWARN 4141) 
DS DEVICE !: MON/MOFF NOT EXECUTED DUE TO ABOVE. 

(CIWARN 4142) 


DS DEVICE !: COMP/NOCOMP NOT EXECUTED DUE TO ABOVE. 
(CIWARN 4143) 
DS DEVICE !: 


DEBUG NOT EXECUTED DUE TO ABOVE. (CIWARN 4144) 


NO DS DEVICES REMAINING TO BE CONTROLLED. (CIWARN 4145) 


RETRY OVERRIDES PREVIOUS RETRY FUNCTION. (CIWARN 4146) 


EXPECTED AN 
(CIERR 4147) 


AS DELIMITER FOR RETRY FUNCTION. 
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4148 INVALID RETRY COUNT, MUST SPECIFY “DEFAULT” OR A NUMBER 


4149 


4150 


4151 


4152 


4153 


4155 


4180 


4181 


4182 


4183 


BETWEEN 0 AND 255 INCLUSIVE. (CIERR 4148) 
DS DEVICE !: RETRY NOT EXECUTED DUE TO ABOVE. (CIWARN 4149) 
DS INTERNAL FIX NUMBERS DIFFER. (CIWARN 4150) 


INCOMPATIBLE OR MISSING NONCRITICAL DS MODULE: DSCOPY, 
DSTEST, DS2026, OR DS2026CN. (CIWARN 4151) 


CRITICAL DS MODULES ARE INCOMPATIBLE, NO CONTROL FUNCTIONS 
EXECUTED. (CIERR 4152) 


MISSING CRITICAL DS SOFTWARE, NO CONTROL FUNCTIONS EXECUTED. 
(CIERR 4153) 


PROMPT OVERRIDES PREVIOUS PROMPT FUNCTION(S). (CIERR 4155) 

REDUNDANT SPECIFICATION OF CANCEL OPTION IGNORED. (CIWARN 4180) 
CANCEL OPTION HAS NO PARAMETERS. (CIERR 4181) 

DS DEVICE ! IS NOT AN X.21 DEVICE; CANCEL NOT EXECUTED. (CIWARN 4182) 


NO CALL REQUEST FOR DS DEVICE !. (CIWARN 4183) 


-DSCOPY GENERAL ERROR MESSAGES 


10 


11 


SUCCEEDED. 

SUCCESSFULLY INITIATED. 

UNABLE TO OPEN TRANSACTION FILE. (NFTERR 4) 

UNABLE TO OPEN LIST FILE (DSCOPYI). (NFTERR 5) 

IC ERROR ON TRANSACTION FILE. (NFTERR 6) 
TRANSACTION RECORD > 200 CHARS LONG. (NFTERR 7) 
TEMPORARY TRANSACTION FILE FULL. (NFTERR 9) 
PARAMETERS IMPLY CONFLICTING MODES. (NFTERR 10) 
CAN’T "RUN" COPY PROCESS IN THIS MODE. (NFTERR 11) 
UNRECOGNIZED PARAMETER. (NFTERR 13) 

CONFLICTING OPTIONS HAVE BEEN SPECIFIED. (NFTERR 14) 


UNIMPLEMENTED FEATURE. (NFTERR 16) 
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Error Codes and Messages 


17 


18 


19 


21 


24 


25 


26 


av 


28 


29 


30 


33 


36 


37 


38 


39 


40 


41 


42 


CANNOT CONTACT REMOTE NODE. (NFTERR 17) 

FILE SYSTEM ERROR ON SOURCE FILE. (NFTERR 18) 
FILE SYSTEM ERROR ON TARGET FILE. (NFTERR 19) 
ILLEGAL DSLINE NAME. (NFTERR 21) 

UNSUPPORTED STANDARD DEVICE TYPE. (NFTERR 24) 
CAN’T FIND OR OPEN THE SOURCE FILE. (NFTERR 25) 
CAN’T CREATE OR OPEN THE TARGET FILE. (NFTERR 26) 
CANNOT CONTACT REMOTE SYSTEM. (NFTERR 27) 


SOURCE AND TARGET FILES CANNOT BE ACCESSED THROUGH REMOTE 
FILE ACCESS. (NFTERR 28) 


COMMUNICATION IO ERROR. (NFTERR 29) 

INSUFFICIENT CAPABILITIES. (NFTERR 30) 

NO SOURCE FILE WAS SPECIFIED. (NFTERR 33) 

DS/3000 HAS NOT BEEN INSTALLED ON THIS SYSTEM. (NFTERR 36) 
REMOTE SYSTEM UNABLE TO USE TRANSPARENT MODE. (NFTERR 37) 


CAN’T FIND THE EXTRA DATA SEGMENT, USE THE DSCOPY INTRINSIC 
TO INVOKE NFT. (NFTERR 38) 


INVALID EXTRA DATA SEGMENT CONTENTS, USE THE DSCOPY INTRINSIC 
TO INVOKE NFT. (NFTERR 39) 


NEGOTIATIONS FAILED, NO COPY CAN BE PERFORMED. (NFTERR 40) 
FILE TRANSFER ABORTED. (NFTERR 41) 


COPY CANCELLED BY USER. (NFTERR 42) 


-DSCOPY INTRINSIC ERROR RETURNS 


80 


81 


82 


83 


BOUNDS VIOLATION. (NFTERR 80) 
SPLITSTACK MODE CALLS NOT ALLOWED. (NFTERR 81) 
FIRST PARAMETER VALUE IS OUT OF RANGE (-1:6). (NFTERR 82) 


SECOND PARAMETER TOO SHORT TO CONTAIN VERSION STRING. 
(NFTERR 83) 

















84 


85 


86 


Error Codes and Messages 
NFT PROCESS IS BUSY, CAN’T START NEW TRANSACTION. 
(NFTERR 84) 
NFT PROCESS IS NOT RUNNING. (NFTERR 85) 


ILLEGAL BASIC CALLING SEQUENCE. (NFTERR 86) 


‘DSCOPY INTERNAL ERRORS 


101 


102 


103 


104 


105 


106 


107 


108 


109 


110 


INTERNAL ERROR ON REMOTE SYSTEM. (NFTERR 101) 

REMOTE SYSTEM NFT VERSION IS INCOMPATIBLE. (NFTERR 102) 
INTERNAL - STRING STORAGE OVERFLOW. (NFTERR 103) 

UNABLE TO CREATE TEMPORARY TRANSACTION FILE. (NFTERR 104) 
AN UNEXPECTED MESSAGE WAS RECEIVED. (NFTERR 105) 

AN ILLEGAL VALUE WAS RECEIVED IN A MESSAGE. (NFTERR 106) 
A MESSAGE RECEIVED IN INVALID FORMAT. (NFTERR 107) 


A REQUIRED ELEMENT WAS MISSING FROM A RECEIVED MESSAGE. 
(NFTERR 108) 


NFT PROCESS CREATE FAILED. (NFTERR 109) 


ATTEMPT TO GET EXTRA DATA SEGMENT FAILED. (NFTERR 110) 


X.21 MESSAGES 


Set 1: Call Progress Signals 


ie 


a: 


i 


20! 


21! 


22! 


23! 


LDEV !/CPS 001 TERMINAL CALLED 

LDEV !/CPS 002 REDIRECTED CALL 

LDEV !/CPS 003 CONNECT WHEN FREE 

LDEV !/CPS 020 NO CONNECTION 

LDEV !/CPS 021 NUMBER BUSY 

LDEV !/CPS 022 SELECTION SIGNALS PROCEDURE ERROR 


LDEV !/CPS 023 SELECTION SIGNAL TRANSMISSION ERROR 


Error Codes and Messages 


41! LDEV !/CPS 041 ACCESS BARRED 

42! LDEV !/CPS 042 CHANGED NUMBER | ” 
43! LDEV !/CPS 043 NOT OBTAINABLE 

44! LDEV !/CPS 044 OUT OF ORDER 

45! LDEV !/CPS 045 CONTROLLED NOT READY 

46! LDEV !/CPS 046 UNCONTROLLED NOT READY 

47! LDEV !/CPS 047 OCE POWER OFF 

48! LDEV !/CPS 048 INVALID FACILITY REQUEST 

49! LDEV !/CPS 049 NETWORK FAULT IN LOCAL LOOP 

61! LDEV !/CPS 061 NETWORK CONGESTION “_" 
71? LDEV !/CPS 071 LONG TERM NETWORK CONGESTION 

81! LDEV !/CPS 081 REGISTRATION/CANCELLATION CONFIRMED 

82! LDEV !/CPS 082 REDIRECTION ACTIVATED 


83! LDEV !/CPS 083 REDIRECTION DEACTIVATED 


Set 2: DCE Provided Information 
1! LDEV !/NPI 001 CHARGE ADVICE - MONETARY CHARGES ! 
2! LDEV !/NPI 002 CHARGE ADVICE - DURATION (SECONDS) ! 


3 ! LDEV !/NPI 003 CHARGE ADVICE - UNITS ! 





10! LDEV */NPI 010 LINE IDENTIFICATION ! 


20! LDEV !/NPI 020 SIGNAL FORMATTING ERROR ! 
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CONVENTIONS 


To call an external procedure from ANS COBOL (COBOL/I), the parameters must be passed by word 
reference. This requirement effectively prevents the COBOL/I user from calling system-level 
intrinsics in general, and specifically, the DS/3000 Program-to-Program intrinsics. The following 
interface routines are provided to allow the ANS COBOL user access to the program-to-program 
communications capability. The user of COBOL II/3000 need not use these interface intrinsics, since 
the call-by-value capability can access the Program-to-Program intrinsics (as outlined in the 
COBOL/II Reference Manual). 


The parameters in the COBOL calling sequences must be of the following types: 


If the parameter is an integer, it must be a COBOL picture 9 through 9(4) or S9(3) computational, 
synchronized. 


If the parameter is a character string, it must be defined as COBOL picture X(n) or A(n), where rn is 
large enough for the required number of characters. 


In the following parameters, those not specifically defined as characters will be assumed to be integers. 
It is assumed that the user is already familiar with DS/3000, in general, and the program-to-program 


intrinsics, specifically. Information regarding formal usage or content of the interface intrinsic 
parameters can be found in Section 6. 


COMMON PARAMETERS 


Parameters whose use 1s the same through all the procedures are: 


ecode integer (required) 
The condition code returned by the PTOP intrinsic. 
-1=CCL 
O=CCE 
1=CCG 


Refer to Section 6 for the meaning associated with these codes in individual PTOP 
calls. 


dsnum integer (required) 
The number returned by CPOPEN, and which is required for all subsequent master 
PTOP calls. The number is always 0 for slave programs. 


ttag A 20-word integer field (optional). 


target A character field used for reading or writing data (required). 
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teount 


integer (required). 
The number of words or bytes to be read or written. Words are a positive integer; 
bytes are negative. | 


INTERFACE INTRINSICS 


CPOPEN 


This procedure is the COBOL callable interface to POPEN. 


Calling Sequence: 


CALL "CPOPEN" USING ecode,dsnum, dsdevice, progname, itag, entryname, parm, 
flags, stacksize, dlsize, maxdata, buffsize 


Where: 


dsdevice 


progname 


ttag 


entryname 


parm 


flags 
stacksize 
dlsize 
maxdata 


buf fsize 


is a character field containing the node name, device class, or logical device number 
of the desired DS line. 


is a Character field containing the name (terminated by a space) of the remote slave 
program. 


is the 20-word integer field sent to and received from the remote program. 


is the character field specifying the secondary entry point (or spaces) where the 
remote program will begin execution. It is ignored if the slave program runs on an 
HP 1000. 


is an integer value to be placed in Q-4 of the slave program. It is ignored if the 
slave program runs on an HP 1000. 


are all MPE parameters used to specify slave program loading options. See Section 
6 of this manual or the MPE Intrinsics Reference Manual for usage. It is ignored if 
the slave system is an RTE system. 


is an integer specifying the maximum number of words which will be transferred 
by any of the PTOP intrinsics. 
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CPREAD 
This procedure is the COBOL callable interface to PREAD. 
Calling Sequence: 


CALL “CPREAD" USING ccode,dsnum,length,target ,teount ,itag 


Where: 

Length is the actual number of words or bytes (depending on the value of teount) read 
into target. (Required.) 

CPWRITE 


This procedure is the COBOL callable interface to PWRITE. 
Calling Sequence: 


CALL "CPWRITE" USING eccode,dsnum,target ,tcount ,itag 


CPCONTROL 
This procedure is the COBOL callable interface to PCONTROL. 
Calling Sequence: 


CALL “CPCONTROL" USING ccode,dsnum,itag 


CPCLOSE 
This procedure is the COBOL callable interface to PCLOSE. 
Calling Sequence: 


CALL "CPCLOSE" USING ecode,dsnum 
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CGET 
This procedure is the COBOL callable interface to GET. 
Calling Sequence: 


CALL "CGET" USING ecode,ifun,itag,il,ionumber 


Where: 
ifun is the function number of the current pending PTOP operation. (Required.) 

O =Anerror occurred. This value is returned only when the condition code CCL 
is also returned. Issue a PCHECK intrinsic call (with a dsnum parameter of zero) 
to determine what happened. 

| = POPEN request received. 

2 = PREAD request received. 

3 = PWRITE request received. 

4 = PCONTROL request received. 

5 = This value is returned only when the condition code CCG 
is also returned. It indicates that a pending MPE File System I/O without wait 
request was completed (instead of the expected remote DS/3000 I/O request). 
tonumber contains the file number associated with the completed I/O request. 

aL is the number of words sent by a PWRITE or the number of words requested by a 

PREAD. 

zonumber is the file number of a non-DS file which completed an I/O without wait. 
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CACCEPT 
This procedure is the COBOL callable interface to ACCEPT. 
Calling Sequence: 


CALL "CACCEPT" USING eccode,itag,target ,teount 


CREJECT 
This procedure is the COBOL callable interface to REJECT. 
Calling Sequence: 


CALL "“CREJECT" USING ccode,itag 


CPCHECK 
This procedure is the COBOL callable interface to PCHECK. 
Calling Sequence: 


CALL "CPCHECK" USING ecode,dsnum,tcode 


Where: 

dsnum integer (required for master, optional for slave). 
For a master program, this number 1s returned by the CPOPEN call. For a slave 
program, this number is always 0. 

tocode is an integer identifying the last error encountered. The error code meanings are 
given in Appendix A, under "DS/3000 Functional Errors." 

EXAMPLE 


The following example illustrates how two COBOL programs, residing on two HP 3000 computers, pass 
data back and forth. These two programs demonstrate and test the intrinsics available to the user of 
the COBOL Program-to-Program facility of DS/3000. The Slave program must be entered on the 
remote system, compiled, and PREPed before the test. The PREPed file must then be made a 

permanent file. In this example, the MPE commands were: 


:COBOL COBOLSS (COBOL Slave Source) 


:PREP $OLDPASS, COBOLS 
:SAVE COBOLS 


The Master program must then be entered, compiled, PREPed, and run on the local system. 


A brief outline of the test follows: 


DS/3000 COBOL Interface 


1. The Master program opens the Slave program with CPOPEN. The t¢aqg array is filled with the 
value of the subscript of each array element, and the CPOPEN intrinsic is called. The Slave displays 
certain parameters involved in the opening. Then the Master also displays the value of the 
parameters used for opening the remote program. After each call is made to a COBOL intrinsic, 
the status of the call is checked in the STATUS-CK-RTN paragraph. 


2. The Master next tests the CPREAD intrinsic by requesting that a message from the Slave be sent 


back. 


3. CPWRITE is tested by sending a message to the Slave. The Slave then displays the message as it was 
received to demonstrate the validity of the text. 


4. The CREJECT-TEST paragraph of the Master is used to test the CPREJECT intrinsic available to 
the Slave as well as the CPCONTROL intrinsic of the Master. The value 14 is moved into the first 
element of ITAG and CPCONTROL is called. Within the paragraph that handles a call to 
CPCONTROL, the Slave tests this value and rejects the request. 


5. The master then calls CPCLOSE to close the remote program before terminating itself. 


The individual programs are shown on the following pages. 


Master PTOP Program 


OO1000$CONTROL USLINIT,SOURCE ,MAP 
001100 IDENTIFICATION DIVISION. 


001200 PROGRAM-ID. MASTER-COBOL. 


001300 ENVIRONMENT DIVISION. 


001400 DATA DIVISION. 


00 1 SOO # 4 96 94-44 46 98 4 46 96 96 46 4 96 46 96 96 HE 96 HE 9 6 6 8 HE 6 HE 2 HE aE a a Ha HE HE 


COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 
COMP 


VALUE 0. 
VALUE 0. 
VALUE 0. 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 0. 
VALUE 0 
VALUE 
VALUE O. 
VALUE SPACES. 


003 OOO 4 4 Ha 96 HE HE HE HE EE HE EHH EHH 


001600 WORKING-STORAGE SECTION. 
001700 7? CCODE PIC $99 
001800 77 DSNUM PIC S99 
001900 77 PARAM PIC $99 
002000 77 FLAGS PIC $99 
002100 77 STACKSIZE PIC $9(4) 
002200 77 DLSIZE PIC $9(4) 
002300 7% MAXDATA PIC $9999 
002400 77 BUFSIZE PIC $999 
002500 77 LGTH PIC $99 
002600 77 ICODE PIC $g9 
002700 77 TCOUNT PIC S99 
002800 77 I PIC $99 
002900 77 DATA-BUF PIC X(66) 
003100 77 A-DOLLAR PIC X(12) 
003200 77 K-DOLLAR PIC X(12) 
003300 77 M-DOLLAR PIC X(26) 
003400 77 O-DOLLAR PIC X(11) 
003500 77 R-DOLLAR PIC X(11) 
003600 7¢f S-DOLLAR PIC X(18) 
003700 77 W-DOLLAR PIC X(12) 
003800 77 CO-DOLLAR PIC X(14) 
003900 77 C9-DOLLAR PIC X(12) 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


"<< ACCEPT >>". 

"## PCHECK ##". 

"HEEEEHREE MASTER ####HH#HE" 
"## POPEN ##". 

"## PREAD ##'. 

"## STATUS CHECK ##". 

"## PWRITE ##". 

"## PCONTROL ##". 

"## PCLOSE ##". 
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004000 77 D1-DOLLAR 
004100 77 EO-DOLLAR 
004200 77 PO-DOLLAR 
004300 77 RO-DOLLAR 
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PIC XXXX VALUE "INDY". 

PIC XX VALUE " ", 

PIC X(7) VALUE “COBOLS ". 

PIC X(12) VALUE "<< REJECT >>". 


0.04400 # 4626 46 44-46 44 9 48 4 48 4 HE Hb HF EH 98 98 aE 4 aE eae HE HE OE aE OE 9 aE 90 48 8 9 8 9 aE a a HE 
004500 01 ITAG-ARRAY. 


004600 


O02 ITAG-ARRAY-MEM PIC 99 OCCURS 20 TIMES. 


0.0.4 7 OC # 44 38 a6 4 94 9 4-4 96 98-06-46 96-46-46 6 96 46 44 46 96 08 EE OF 4 9 48 HE aE aE E96 6 98 98 46 Ot 98 2 a a aE aE HE 


004800+* 


PROCEDURE DIVISION * 


0.049 00 # #1 06 46 44 44 4 44 9 a 4 46 He OF Ht OE Oe at 4 6 6 OE ae 96 at 4 96-20 HE aE aE HEE OE 6 OE OE OE 9 4 Ha HE a HE 


005000 PROCEDURE DIVISION. 
005100 DRIVER-PARA. 


005200 
005300 
005400 
005500 
005600 
005700 
005800 
005900 
006000 
006100 
006200 
006300 
006400 
006500 
006600 
006700 
006800 
006900 
007000 
007100 
007200 
007300 
007400 
007500 
007600 
007700 
007800 
007900 
008000 
008100 
008200 
008300 
008400 
008500 
008600 
008700 
008800 
008900 
009000 
009100 
009200 
009300 


PERFORM ISSUE-AN-OPEN. 
PERFORM ISSUE-A-READ. 
PERFORM ISSUE-A-WRITE. 
GO TO CREJECT-TEST. 
GO TO PCLOSE-CALL. 


ISSUE-AN-OPEN. 


DISPLAY M-DOLLAR. 

DISPLAY O-DOLLAR. 

PERFORM LOOPI VARYING I FROM 1 BY 1 UNTIL 
I IS GREATER THAN 20. 

DISPLAY " TAG TO BE SENT: ". 

DISPLAY ITAG-ARRAY. 

CALL "“CPOPEN' USING CCODE, DSNUM, D1-DOLLAR, PO-DOLLAR, 
ITAG-ARRAY, EO-DOLLAR, PARAM, FLAGS, STACKSIZE, DLSIZE, 
MAXDATA, BUFSIZE. 

PERFORM STATUS-CK-RIN. 

DISPLAY O-DOLLAR. 

DISPLAY " CCODE=", CCODE, " DSNUM="", DSNUM, 

" PARAM=", PARAM. 

DISPLAY " FLAGS=", FLAGS, " STACKSIZE=", STACKSIZE. 

DISPLAY © DLSIZE=", DLSIZE, " MAXDATA=", MAXDATA. 

DISPLAY " BUFSIZE=", BUFSIZE, " LGTH=", LGTH. 

DISPLAY " PROGNAME=", PO-DOLLAR. 

DISPLAY " ITAG-ARRAY RECEIVED: ". 

DISPLAY ITAG-ARRAY. 


ISSUE-A-PREAD. 


DISPLAY R-DOLLAR. 

PERFORM LOOPI VARYING I FROM 1 BY 1 UNTIL 

I IS GREATER THAN 20. 

DISPLAY "ITAG TO BE SENT: ". 

DISPLAY ITAG-ARRAY. 

CALL "CPREAD" USING CCODE, DSNUM, LGTH, DATA-BUF, 
TCOUNT, ITAG-ARRAY. 

PERFORM STATUS-CK-RTN. 

DISPLAY " CCODE=", CCODE, " DSNUM=", DSNUM, 
“ LGTH=", LGTH. 

DISPLAY " DATA RECEIVED FROM SLAVE: ". 

DISPLAY DATA-BUF. 

DISPLAY “ ITAG RECEIVED: ". 

DISPLAY ITAG-ARRAY. 


ISSUE-A-WRITE. 


DISPLAY W-DOLLAR. | 
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009400 
009500 
009600 
009700 
009800 
009900 
010000 
010100 
010200 
010300 
010400 
010500 
010600 
010700 
‘010800 
010900 
011000 
011100 
011200 
011300 
011400 
011500 
011600 
011700 
011800 
011900 
012000 
012100 
012200 
012300 
012400 
012500 
012600 
012700 
012800 
012900 
013000 
013100 
013200 
013300 
013400 
013500 
013600 


PERFORM MULTIPLY-LOOP VARYING I FROM 1 BY 1 UNTIL 
I IS GREATER THAN 20. 
DISPLAY " ITAG TO BE SENT: ". 
DISPLAY ITAG-ARRAY. 
MOVE "THIS IS THE DATA FROM PWRITE TEST." TO DATA-BUF. 
CALL “CPWRITE” USING CCODE, DSNUM, DATA-BUF, TCOUNT, 
ITAG-ARRAY. 
PERFORM STATUS-CK-RTN. 
DISPLAY " CCODE=", CCODE, " DSNUM=", DSNUM. 
DISPLAY " ITAG RECEIVED: ". 
DISPLAY ITAG-ARRAY. 
CREJECT-TEST. 
DISPLAY CO-DOLLAR. 
MOVE SPACES TO ITAG-ARRAY. 
MOVE 14 TO ITAG-ARRAY-MEM(1). 
DISPLAY “ITAG TO BE SENT: ". 
DISPLAY ITAG-ARRAY. 
CALL "CPCONTROL" USING CCODE, DSNUM, ITAG-ARRAY. 
PERFORM STATUS-CK-RTN. 
STOP RUN. 
LOOPI. 
MOVE I TO ITAG-ARRAY-MEM(I). 
MULTIPLY-LOOP. 
MULTIPLY 2 BY ITAG-ARRAY-MEM(I). 
STATUS-CK-RTN. 
IF CCODE IS LESS THAN ZERO GO TO 
SOMETHING-WENT-WRONG. 
IF CCODE IS GREATER THAN ZERO GO TO 
REQUEST-REJECTED. 
DISPLAY S-DOLLAR, "EVERYTHING OKAY". 
REQUEST-REJECTED. 
DISPLAY S-DOLLAR, “REQUEST REJECTED BY SLAVE". 
GO TO PCLOSE-CALL. 
SOMETHING-WENT-WRONG. 
DISPLAY S-DOLLAR, “CCL--SOMETHING IS WRONG". 
CALL "CPCHECK" USING CCODE, DSNUM, ICODE. 
DISPLAY K-DOLLAR, " CCODE=", CCODE, 
" ICODE=", ICODE. 
PCLOSE-CALL. 
DISPLAY C9-DOLLAR. 
CALL "CPCLOSE" USING CCODE, DSNUM. 
DISPLAY " CCODE=", CCODE, " DSNUM=", DSNUM. 
STOP RUN. 
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Slave PTOP Program 


OO1000$CONTROL USLINIT,SOURCE 


001100 
001200 
001300 
001400 


IDENTIFICATION DIVISION. 
PROGRAM-ID. SLAVE-COBOL. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 


OD 1 SOO 4 46 4 at 48 4 9 Fe He 96 EH HE 2E HE 9 26 96 aE 26 46 56 96 2b Ob a8 OE HE Ob OE 26 OE OE 4 HE 06 4b 98 26 Ht 06 Ht 6 


001600 
001700 
001800 
001900 
002000 
002100 
002200 
002300 
002400 


WORKING-STORAGE SECTION. 


7T PIC $99 USAGE COMP. 

(7 iI PIC $99 COMP VALUE 0. 

tT? CCODE PIC $99 COMP VALUE 0. 
7? IFUN PIC $9 COMP VALUE 0. 
(7 IL PIC $99 COMP VALUE 0. 
77 IONUMBER PIC $99 COMP VALUE 0. 
tf ICODE PIC S99 COMP VALUE 0. 
77 DSNUM PIC $99 COMP VALUE 0. 


OO2S OOM 2t 3 4 96 44 36 5 6 98 96 EE aE 3 HE E98 HE ae HE HE E96 HE HE 9 4 EE 98 a8 9 48 8 08 96 48 98 98 8 a 


002600 
002700 
002800 
002900 
003000 


77 C-DOLLAR PIC X(11) 
77 G-DOLLAR PIC x(9) 

77 A-DOLLAR PIC X(12) 
77 R-DOLLAR PIC X(12) 
77 S-DOLLAR PIC x(25) 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


"## CHECK ##". 

"## GET ##". 

"## ACCEPT ##". 

"## REJECT ##". 

“#HERBRHRE SLAVE ##### #888". 


O03 1 OC 46 56 ta 96 46 He 30 96 46 a6 26 96 HE HE aE Ee HE aE SE HE OE 28 HE HE 2 HE aE HE HE HE 96 HE 9 8 ae EH 0 HE 


003200 
003300 
003400 
003500 
003600 


77 OO-DOLLAR PIC X(11) 
77 CO-DOLLAR PIC X(14) 
77 SO-DOLLAR PIC X(18) 
77 RO-DOLLAR PIC X(11) 
77 WO-DOLLAR PIC X(12) 


"<< POPEN >>". 

"<< PCONTROL >>". 

"## STATUS CHECK ##". 
"<€< PREAD >>". 

"<< PWRITE >>". 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


0.03 TOO 4 46 46 46 4 4b 4 46 96 48 Hb ae a6 E96 46 ab tHE He 2 HE HE 98 2 aE 4b HE SE OE 48 96 8 96 98 aE HE 98 6 26 98 98 EE 


003800 
003900 
004000 
004100 


01 DATA-ARRAY. 

O2 DATA-ARRAY-MEM PIC 99 OCCURS 33 TIMES. 
01 ITAG-ARRAY. 

O2 ITAG-ARRAY-MEM PIC 99 OCCURS 20 TIMES. 


eer eee tre rrr rrrrrrrrrT rr tr TTT 


004300* 


PROCEDURE DIVISION # 


O04 OOH 4 46 a6 6-H. 4 46 a Hk HE HE He HE HE aE aE at HE HE ae HEE ea HE 9 HE HE HE 2 HE ae HE HE HE ae HE aE OE OE aE 96 Hb aE 8 8 EE 


004500 
004600 
004700 
004800 
004800 
005000 
005100 
005200 
005300 
005400 
005500 
005600 
005700 
005800 
005900 
006000 
006100 


PROCEDURE DIVISION. 
START-OF -SLAVE. 
DISPLAY S-DOLLAR. 
CALL “CGET’" USING CCODE, IFUN, ITAG-ARRAY, IL, IONUMBER. 
PERFORM PRINT-GET-PARAMS THROUGH CHECK-RETURN-CC. 
IF CCODE IS NOT EQUAL TO ZERO GO TO CREJECT-PAR. 
GO TO POPEN, PREAD, PWRITE, PCONTROL DEPENDING ON IFUN. 
POPEN. 
DISPLAY S-DOLLAR. 
DISPLAY OO-DOLLAR. 
MOVE ZEROES TO ITAG-ARRAY. 
GO TO CACCEPT-PAR. 
PREAD. 
DISPLAY S-DOLLAR. 
DISPLAY RO-DOLLAR. 
PERFORM LOOP1 VARYING I FROM 1 BY 1 UNTIL 
I IS GREATER THAN 20. 
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006200 
006300 
006400 
006500 
006600 
006700 
006800 
006900 
007000 
007100 
007200 
007300 
007400 
007500 
007600 
007700 
007800 
007900 
008100 
008200 
008300 
008400 
008500 
008600 
008700 
008800 
0083900 
009000 
009100 
009200 
009300 
009400 
009500 
009600 
009700 
009800 
009900 
010000 
010100 
010200 
010300 
010400 
010500 
010600 
010700 
010800 
010900 
011000 
011100 


PERFORM INCREASE-LOOP VARYING T FROM 1 BY 1 UNTIL 
T IS GREATER THAN IL. 
GO TO CACCEPT-PAR. 
LOOP7. 
MOVE 7 TO ITAG-ARRAY-MEM(I). 
LOOP1. 
MOVE 1 TO ITAG-ARRAY-MEM(I). 
LOOP2. 
MOVE 2 TO ITAG-ARRAY-MEM(I). 
INCREASE-LOOP. 
MOVE T TO DATA-ARRAY-MEM(T). 
PWRITE. 
DISPLAY S-DOLLAR. 
DISPLAY WO-DOLLAR. 
PERFORM LOOP? VARYING I FROM 1 BY 1 UNTIL 
I IS GREATER THAN 20. 
CACCEPT-PAR. 
' CALL "CACCEPT” USING CCODE, ITAG-ARRAY, DATA-ARRAY, IL. 
PERFORM CHECK-RETURN-CC. 
IF IFUN = 3 PERFORM PRINT-DATA. 
GO TO START-OF-SLAVE. 
CREJECT-PAR. 
CALL "CREJECT" USING CCODE, ITAG-ARRAY. 
PERFORM CHECK-RETURN-CC. 
GO TO START-OF-SLAVE. 
PCONTROL. 
DISPLAY CO-DOLLAR. 
IF ITAG-ARRAY-MEM(1) = 14 GO TO CREJECT-PAR. 
PERFORM LOOP2 VARYING I FROM 1 BY 1 UNTIL 
I IS GREATER THAN 20. 
GO TO CACCEPT-PAR. 
PRINT-DATA. 
DISPLAY “DATA RECEIVED FROM THE MASTER: “. 
DISPLAY DATA-ARRAY. 
PRINT-GET-PARAMS. 
DISPLAY “ CCODE=", CCODE, “ IFUN=", IFUN, “ IL=", IL, 
" TONUMBER=", IONUMBER. 
DISPLAY "ITAG RECEIVED: “. 
DISPLAY ITAG-ARRAY. 
CHECK-RETURN-CC. 
IF CCODE IS NOT EQUAL TO ZERO 
PERFORM SOMETHING-WENT-WRONG. 
DISPLAY SO-DOLLAR, “EVERYTHING OKAY". 
SOMETHING-WENT -WRONG. 
CALL "“CPCHECK" USING CCODE, DSNUM, ICODE. 
DISPLAY " CCODE=", CCODE, ° ICODE=", ICODE. 
ERROR-EXIT. 
DISPLAY "## SLAVE PROGRAM EXITING ##". 
STOP RUN. 
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CONVENTIONS 


When parameters are specified in the CALL statement the BASIC/ 3000 Interpreter (and compiled 
BASIC) sets up a parameter address table. The parameter address table consists of: 


e The number of parameters. 

e Acode word for each parameter, specifying data type and dimensioning. 
e Areference pointer to each parameter. 

See Appendix F of the BASIC / 3000 Interpreter Manual. 


Because the DS/3000 intrinsics are program-to-program, the BASIC/3000 slave must be a compiled 
and PREPed program. The master program may be either running on the Interpreter or run asa 
compiled program. 


It is assumed that the user is already familiar with DS/3000 in general and the program-to-program 
intrinsics specifically. Information regarding formal usage or content of the interface intrinsic 
parameters can be found in Section 6. 


COMMON PARAMETERS 


Parameters whose usage 1s the same throughout the procedures are: 


ecode integer. 
Condition code returned by the DS/3000 Program-to-Program intrinsic. 


-3 = not enough user stack for data transfer. 
-2=CCL 

0=CCE 

12=CCG 


dsnum integer. 
The DS/3000 communication line number. (analagous to FOPEN file number) 


ttag integer. 
A 20-word array. 


Parameters The BASIC-DS/3000 interface routines pack and unpack the data specified in the 
parameter lists of the master and the slave programs. The user must insure that the 
number of parameters specified on the master and the slave sides are the same and 
that the data types correspond. If the sending and receiving data types are not the 
same, the resulting data will be unpredictable. — 
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Special care must be taken when passing string variables (simple strings or string arrays). String 
variables have both a physical (ie. maximum) length and a logical (ie. current) length. The logical 
length is never greater than the physical length and may, in fact, be smaller. Since PTOP packs string 
variable parameters according to their logical lengths, but unpacks according to the physical length of 
the receiving string variables, the same string variable cannot be used for both sending and receiving if 
its physical length exceeds its logical length. 


For example, suppose NO$ is a 10 character string which currently has the value JOHN. N’s physical 
length is 10 but its logical length is only 4. If a master PTOP program were to BPWRITE NO$, only 4 
characters of data will be sent across the line. If the slave PTOP program were to call BACCEPT with 
another 10 character string, say MO$, the value of MO$ after the BACCEPT would be JOHNxxxxxx, 
where the xs are undefined. The logical length of MO$ would now be equal to its physical length, 
which is 10. 


As another example, suppose the master PTOP program were to pass two 10 character strings to 
BPWRITE (NO$ and N1$), and the slave PTOP program called BACCEPT with two 10 character strings 
(MO$ and M1$). If NO$ = JOHN and N1$ = JANE DOE, the resulting values of MO$ and M1$ would be 
JOHN JANE and DOExxxxxxx, respectively. (The xs are undefined characters.) 


These anomalies are consistent in BASIC with the rules governing access to other media in which the 
length of strings is not inherent (for example, binary files). There are several ways to avoid these 
problems. The first method, which is illustrated in the example BASIC PTOP programs in this section, 
is to pad all strings with blanks before transmitting them (ie. before BPWRITE or before BPACCEPT of 
a BPREAD). Another, more sophisticated approach, would be for the sending side to pass the logical 
lengths of the strings in the ttag array. The receiving side would supply only one parameter, a string 
which is large enough to hold all of the strings which were sent. This string could then be unpacked 
by the user program using the information in the tag array and the substring functions of BASIC. 


There is one more anomaly involved in passing strings. Since strings are always unpacked starting on 
word boundaries, it is not possible to unpack an even length string into two odd length strings. 
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BPOPEN 
This procedure is the BASIC callable interface to POPEN. 


Calling Sequence: 


CALL BPOPEN(ccode ,dsnum,dsdevice,progname , ied 2 ‘e a ae — 


stacksize) {dlsize)\ {maxdata 
0 >10 *10 : 


buffsize) 
Where: 
dsdevice string. 
The DS line class, node name, or logical device number (string must have at least 
one trailing blank). 
progname string. 
Name of remote slave program (terminated with a blank). 
entryname string. 
Secondary entry point into the slave program (terminated with a blank). 
param integer. 
Value placed in Q-4 of the slave program stack. 
flags MPE parameters used to control slave program loading. See Section 6 of this 
stacksize manual or the MPE Intrinsics Reference Manual for usage. 
dlsize 
maxdata 
bufsize integer. 


Maximum number of words per PTOP transfer. 
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BPREAD 
This procedure is the BASIC interface routine to PREAD. 


Calling Sequence: 
CALL BPREAD(ccode ,dsnum, igth 0°"), param list) 


Where: 


lgth integer. 
Number of words received in transfer. 


param list := param [,param list] where paramis any BASIC supported data type (such as 
STRING, INTEGER, REAL ARRAY) 


NOTE 


The BASIC interface routines: BPREAD, BPWRITE, and 
BACCEPT differ significantly from the PTOP intrinsics in 
the target/tcount vs. parameter list data schemes. 

The parameter list allows the BASIC user to send and 
receive heterogeneous data items. A contiguous buffer 1s 
built on the User’s stack for the transfers. 


BPWRITE 
This procedure is the BASIC callable interface to PWRITE. 


Calling sequence: 


CALL BPURITE (ceode dsnum,4 4°9\, param list) 


BPCONTROL 
This procedure is the BASIC interface routine to PCONTROL. 
Calling Sequence: 


CALL BPCONTROL (ecode ,dsnum,itag) 

















DS/3000 BASIC Interface 


BPCLOSE 
This procedure is the BASIC interface routine to PCLOSE. 
Calling Sequence: 


CALL BPCLOSE(ccode ,dsnum) 


BGET 
This procedure is the BASIC interface routine to GET. 


Calling Sequence: 


CALL BGET(ccode, ifun da “9,00 \ dno ) 


Where: 

tfun integer. 
Receives the function code from the request issued by the remote master program. 
(Refer to Section 6 for 7 fun meanings.) 

il integer. 
The number of words expected or sent on BPREAD or BPWRITE. 

ztonumber integer. 
Valid if both ecode=1 and ifun=5. File number of completed non-DS I/O 
without wait. 

BACCEPT 


This is the BASIC callable interface routine to ACCEPT. 


Calling Sequence: 


CALL BACCEPT(ccode,i fun §o 9S, param list) 
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BREJECT 
This is the BASIC callable interface routine to REJECT. 
Calling Sequence: 


CALL BREJECT (ccode ,itag) 


BPCHECK 
This is the BASIC callable routine to PCHECK. 
Calling Sequence: 


CALL BPCHECK(ccode ,dsnum,ticode) 


Where: 

dsnum integer. 
For a master program, this number is returned by BPOPEN. For a slave program, 
this number is always 0. 

itcode integer. 
The number returned identifies the last error encountered. Refer to Appendix B, 
under the heading "DS/3000 Functional Errors", for meaning. 

EXAMPLES 


Master PTOP Program 


MASTER 

1 REM ‘ DE He He 4 He IE SE SE HE FG HE 6 HE HE 48 6 48 46 48 4G 4b SE OE 96 HE SE 4G So SE ae 3b 2 SE EE 2G FE SE SEE 9 HE 9 4b 5G EE Se ot 
2 REM: 
3 REM: MASTER PTOP PROGRAM 
4 REM: 
TG REM ¢ 94 a6 at 96 46 96 46 46 4 0 Ht 4 96 E46 HE HE HE HE HE HE EH 2 SE He HE HE aE HE 2 He HE HEE HE HEE HE EE 2 8 EH HE 8 HE HE EE at 
6 REM: 
7 REM: THIS PROGRAM ISSUES A BPOPEN TO THE SLAVE PROGRAM AND 
8 REM: USES THE TAG FIELD TO SEND SUBTYPES FOR THE BREAD/BWRITE 
9 REM: OPERATIONS. 

10 REM: 

1 1 REM 4 $b 4b 46 4 9b 9G Se OE 9b Se 4 OF FE 4G HE 46 96 4b 6 44 48 96 46 9b 9b SEE SE OE aE 4e 4E SE SE HE HE aE SE 46 48 9G 4b 96 26 EE OF OE EE 6 

110 REM: DATA DECLARATIONS 


120 REM: 24:46 44 46 46 46 46 96 94 46 6 48 a6 9 96 ta aE HEE HEE HEE HEE HE aE HEE EG HE HE HE GE HE ae aE a aE aa 
130 REM: BASIC PTOP INTRINSIC PARAMETERS-- 

140 INTEGER C,D,F,I10,L 

150 REM: C=CC, D=DSNUM, F=FLAGS, IO=ICODE, L=LENGTH 

160 INTEGER 1I1[20] 

165 MAT I1=ZER 











170 
180 
190 
200 
210 
220 
221 
222 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 
325 
330 
335 
340 
345 
360 
370 
380 
390 
400 
410 
420 
430 
440 
450 
460 
470 
480 
490 
500 
510 
520 
530 
540 
550 
560 
970 
580 
590 
600 
610 
620 
630 
640 
650 
660 
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REM: I1[#]=TAG FIELD 
DIM DO$[10] ,Po$[10] 
REM: DO$=DSLINE, PO$=REMOTE PROGRAM 


REM: 


n---- LOCAL VARIABLES----- 


DIM N1$[20] ,N2$[20] ,A1$[20] ,R$[40] 

REM: Ni$,N2$=NAMES; A1$[20]=ADDRESS; R$=RECORD(NAME, ADDRESS) 
DIM B$[20] 

REM: B$= BLANK PADDING STRING 

DIM C$[20] ,N$[22] 

REM: C$=USER COMMAND/TEXT LINE 

REM: N$=ENTER NAME MESSAGE 


MAUMLEARE SELES TT Te ES Pe ee TT PT 


REM: 
REM: 
REM: 


START OF PROCESSING 


PREM ¢ 34-36-36 45 96 96 96 98-96 8 96 98 36 96 He HE 9E 96 HE EE 98 HE ME Hh HE HE HE 96-44 98 08 a6 HR HE 9 HE HEE 2 28 90 8 08 ab 28 28 4 E 


REM: 
PRINT 


----INITIALIZATION OF VALUES AND BPOPEN----- 
"ENTER DSLINE CLASS NAME" 


INPUT DO$ 


PRINT 
INPUT 


“ENTER SLAVE PROGRAM NAME" 
PO$ 


N$="ENTER NAME ” 


B$=" 


CALL BPOPEN(C,D,D0$, PO$) 
IF C=O THEN GOTO 410 


PRINT 
GOSUB 
STOP 


"“### ERROR ON BPOPEN ###" 
7000 


REM ¢ 2656 46 44 46 4 Ho 6 0b 9b 6 aE Hee HE HE ae SE HE 56 HE Ob HE 98 aE Oe HE HE 5 96 4 HE HG AE 4 98 5 aE HE 6 9b HE 0 a He EH 


REM: 


WELCOME MESSAGE AND MENU 


PREM ¢ 4494 46 94 46 26 26-46 46 46 28 HE HF 98 HE 9 HE EE 8 HE HE aE HE 48 HE HE HE aE 48 HE 4 HE HE 2 a HH 6 9 E98 20 a 9 a ae aE at 2 HE 


PRINT "MASTER AND SLAVE PTOP RUNNING" 

PRINT ° " 

PRINT “### OPERATIONS MENU ###" 

PRINT " N - NAME CHANGE" 

PRINT " A - ADDRESS CHANGE” 

PRINT " I - INSERT PERSON" 

PRINT " D - DELETE PERSON" 

PRINT " LN - LIST NAME AND ADDRESS" 

PRINT " LA - LIST ALL NAMES AND ADDRESSES" 
PRINT " EX - EXIT PROGRAM" 

NILE ECOCLOLOL ELS SCL Le ere rrerrrererrerrr nT fr rr ener rt rr er 
REM: OPERATION REQUEST 

NACE OOOO L ITE L Pree errr rrerrrer tof T rT rere rr rr Tre et tT 
PRINT " " 

PRINT "ENTER OPERATION" 

LINPUT C$ 

IF C$[1,1]="N" THEN GOTO 1000 

IF C$[1,1]="A" THEN GOTO 2000 

IF C$[1,1]="I" THEN GOTO 3000 

IF c$[1,1]="D" THEN GOTO 4000 

IF C$[1,2]="LN" THEN GOTO 5000 


IF C$[1,2]="LA" THEN GOTO 6000 
IF c$[1,2]="Ex" THEN GOTO 8000 
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670 

680 
1000 
1010 
1020 
1030 
1040 
1045 
1050 
1060 
1070 
1080 
1084 
1085 
1086 
1090 
1100 
1110 
2000 
2010 
2020 
2030 
2040 
2050 
2060 
2070 
2080 
2084 
2085 
2086 
2090 
2100 
2200 
3000 
3010 
3020 
3030 
3040 
3050 
3060 
3070 
3080 
3084 
3085 
3086 
3090 
3100 
3110 
4000 
4010 
4020 
4030 
4040 
4050 


PRINT "### UNRECOGNIZED OPERATION ###" 

GOTO 450 

REM ¢ 26-26 46 56 96 96 96 46 96 96 06 46 06 98 96 46 98 46 HF 46 26 OE 4 06 9b 06 96 HE 96 26 aE 9E HE 4E 6 9 E46 6 aE 98 26 06 96 46 0 28 06 48 08 46 46 06 1 
REM: NAME CHANGE 

REM ¢ 96 96 9 26 96 26 56 08 06 96 46 96 6 4b 96 HE 96 OE 9b HE 5b HE HE OE 4 aE 54 OE 46 2E 96-9 SE aE OE 9 OE 28 96 9E 06 OE OE 46 96 aE OF 0 OO 96 08 08 8 at 
PRINT N$ 

LINPUT N1$ 

IF N1$="" THEN GOTO 450 


IF I11[1]<O OR 11[1]>1 THEN GOSUB 7000 

PRINT "ENTER NEW NAME" 

LINPUT N2$ 

11[1]=1 

REM: PAD STRINGS WITH BLANKS BEFORE XMITTING 

N1$=N1$+B$ 

N2$=N2$+B$ 

CALL BPWRITE(C,D,11[#] ,N1$,N2$) 

GOSUB 7000 

GOTO 1000 

REM 9 He HE HE HE HE OE He HE OE 9G 58 HE 4E 2 46 HE 46 HE 4E 9 HE HE EE 0E 96 26 2G HE OE EE HE HE 46 HE HE HEE OE 96 2 Ho HE He OE HE 9b 96 OE HE OF 
REM: ADDRESS CHANGE 

REM © HE HE HE I HE HE He HE SE IE HE Me SE HE HE Ht UE HE Ob HE HE SE HG OE SE OE 4 FE OEE 26 EOE OE 4e aE HE SE HE aE HE 48 He 46 de HE EOE HE 4 HE EE 
PRINT N$ 

LINPUT N1$ 

IF Ni$="" THEN GOTO 450 

PRINT “ENTER NEW ADDRESS" 

LINPUT A1$ 

11[1]=2 

REM: PAD STRINGS WITH BLANKS 

N1$=N1$+B$ 

A1$=A1$+B$ 

CALL BPWRITE(C,D,11[#] ,N1$,A1$) 

GOSUB 7000 

GOTO 2000 

REM © SE 96 dE IG HE AE HE SE FE HE HE HE 46 HE HE 46 46 SE 26 OE 4 HE HE OE 46 9G 28 aE 46 SE 4E aE 46 9G OE OE HE HE 96 4 HE 26 4 98 6 HE 46 6 HE SE 4 46 98 
REM: INSERT NAME 

REM © Fe He ae 4G HE HE He AE HE 4 HE 6 6 9E at HE HE 46 HE HE HE 9G 46 OE He He SE 6 HE EE He EE HE EE HE 4 OE He 96 HE 8 46 HE HE 46 98 28 08 06 8 
PRINT N$ 

LINPUT N1$ 

IF N1$="" THEN GOTO 450 

PRINT "ENTER ADDRESS" 

LINPUT A1$ 

11[1]=3 

REM: PAD STRINGS WITH BLANKS 

N1I$S=N1$+B$ 

A1$=A1$+B$ 

CALL BPWRITE(C,D,11[*] .NI$,A1$) 

GOSUB 7/000 

GOTO 3000 

REM © He HG OE 9G He He TE He HE OE Sb Se Oe SE He He HE HE HE HE HE OE SE OE HE EG He He HE HE HE SE OE HE EE HE HE 5b HE 46 48 0 OE HE aE 06 Ob et OE EE 
REM: DELETE PERSON 

REM © FE He HE ME HE HE HE HE HE 5G HE OE Oe HE HE AE He OE HE He AE HE HE OE EE HE HE HE HE Hk HE aE SE HE HE HE HE HE Ob EE 4b 48 Ht HE 0 4 HE aE HE ae 
PRINT N$ 

LINPUT Ni$ 

IF N1i$=""" THEN GOTO 450 

















4060 
4065 
4066 
4070 
4080 
4090 
5000 
5010 
9020 
5030 
5040 
5050 
5060 
5067 
5068 
9070 
5080 
5090 
5100 
9110 
5120 
5130 
5140 
6000 
6010 
6020 
6030 
6040 
6050 
6060 
6070 
6080 
6090 
7000 
7010 
7020 
1030 
1040 
7050 
1060 
1065 
1070 
7080 
7090 
7100 
7110 
7120 
7130 
7140 
7150 
7160 
7170 
7180 
8000 
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11[1]=4 

REM: PAD NAME WITH BLANKS 

NIS=N1$+B$ 

CALL BPWRITE(C,D,11[*] ,N1$) 

GOSUB 7000 

GOTO 4000 

REM ¢ 224 46 9 9 46 96 at 46 46 96 96 06 96 46 26 OF 46 96 46 06 26 OF 96 HE 4E HE 9 96 96 HE SE HE OE 4 4G HE 8 HE 96 5 9 OF 4 28 96 96 96 26 2E OF 08 48 HE 
REM: LIST NAME AND ADDRESS 

REM ¢ 2644-96 96 46 96 96 46 96 46 96 46 46 9b 46 46 OE 46 9 96 Hb 46 6 96 26 OE 9E 46 46 HE HE 96 9F 6 56 ae OE HE 96 9648 96 9b 98 46 48 HE OE 96 98 46 28 OE at 
PRINT N$ 

LINPUT N1$ 

IF N1i$="" THEN GOTO 450 

Tif{i]=1 

REM: PAD NAME WITH BLANKS 

NIS=N1$+B$ 

CALL BPWRITE(C,0,11[*] ,NI$,N1$) 

IF C=O THEN CALL BPCONTROL(C,D,1I1[#]) 

IF C<>0 OR I1[1]<>1 THEN GOTO 5000 

L=-80 

CALL BPREAD(C,D,L,11[#*] ,R$) 

GOSUB 7000 

PRINT R$ 

GOTO 5000 

FEM ¢ 26-34 46 44 46 96 96 98 96 96 96 96 46 96 46 4b at HE OE 6 aE HE HE 9E OE HE HE 4b 96 9 HE 46 96 26 28 9E HE 9E 6 44 94 HE OE 9E 26 9 96 OE HE HE 4 00 0 
REM: LIST WHOLE LIST 

REM ¢ 9 2 46 96 96 48 48 90 4 48 48 96 Hh 2 2b 26 6 48 aE 2b 4 Ob aE HE HE 6 OE 96 96 96 44 9 46 96 26 a8 HE HE OE ab 46-96 46 9G HE HE HE 2 46 46 96 48 OE 
L=-80 

I1({1]=2 

CALL BPREAD(C,D,L,11[#] ,R$) 


GOSUB 7000 

PRINT R$ 

IF I11[1]=0 THEN GOTO 6000 

GOTO 450 

REM ¢ 4 46 46 46 46 96 6 2t 96 6 26 6 HE 96 16 46 56 a6 46 46 96 OE 48 26 26 46 46 96 46 56 46 56 HE 9G 28 96 96 FE 0 9b 8 4E 96 46-46 48 54 98 46 0 20 8 EE 
REM: CONDITION CODE AND STATUS CHECK 


REM ¢ 4 4644 3 96 46 4 26 96 46 96 96 98 96 96 96 96 46 96 48 48 46 E48 26 96 96 HE 2b 9b AE 26 96 96 26 96 9b HE HE 2b a6 46 98 96-96 96 96 96 48 26 46 96 46 46 
IF C>O THEN GOTO 7120 

IF C<O THEN GOTO 7150 

CALL BPCONTROL(C,D,11[#]) 

IF 11[1]<O OR I1[1]>1 THEN GOTO 7090 

REM: REMINDER--CHECK ABOVE LINE 

REM: ### EVERYTHING OKAY ### 

RETURN 

REM: ### BAD RECORD ##+# 

PRINT "### NON-EXISTENT RECORD ###" 
RETURN 

REM: ### CCG ### 

PRINT “### REQUEST REJECTED BY SLAVE ###" 
RETURN 

REM: ### CCL ### 

CALL BPCHECK(C,D, IO) 

PRINT “### PTOP ERROR:";10;" ###" 

RETURN 


MAUMEE LSS er te ee rrr rrrrrrrrr rrr rer rT TT TT 
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8010 REM: EXIT 
8020 REM SHHEHHHHHHHHHBRHHHHERKKHKEHHEHHHHRHEHHHHHHEKHHEHRHEHEHEHHEHEEE » 
8030 CALL BPCLOSE(C,D) i 
8040 GOSUB 7000 

8050 END 
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Slave PTOP Program 





SLAVEBF 

1 REM z 4:46 96 46-46-96 96 46 96 46-46-46 48 6 48 96 98 48 96 96 HE 4 HE 9 06 HE HE HE HE HE HE HE aE HE OE HE HE HE HE EE HE HE HE SE dE EE HE a OO HE Ht 9 

2 REM: 

3 REM: SLAVE PTOP PROGRAM 

4 REM: 

S REM sz 0646 96 6 6 96 96 46 96 4 46 Ht 48 5 2 ae at a HE Ht Oe 46 HE HE 4 aE HE aE HE OE HE Ee SE SE 6 tt HE HE HE HE HE AE OE HE 48 0 06 a a 4 Ht 

6 REM: 

7 REM: THIS PROGRAM ACCEPTS DATA FROM THE MASTER AND 

8 REM: ACCORDINGLY CHANGES, INSERTS, OR DELETES ENTRIES. 

9 REM: IT ALSO TRANSMITS NAME/ADDRESS RECORDS TO THE MASTER 
10 REM: 
100 REM sz 24646 9 4 96 96 48 48 94 96 56 26 8 8 08 98 a8 Ht at 96 OE 96 HE 96 98 9 HE SE HE HE OE HE HE OE HE Hb OE 8 HE a HE He OE OE HE 4 aE OE 96 8 HE Ot Ot 
110 REM: DATA DECLARATIONS 
120 REM zg 8 46-26 96 44 96 56 56 46 44 46 96 08 at 96 at 96 96 96 26 He Ob HE aE HE EE 8 26 8 HE 26 ae HE OE HE ab HE A HEE OE HE Ob 9b aE OE 28 06 OE 28 OE et 
130 REM: ----- BASIC PTOP INTRINSIC PARAMETERS----- 


140 INTEGER C,F,L,10,1,0 

150 REM: C=CC; F=FUNCTION; L=IL; I10=1/0; I=ICODE; D=DSNUM 
155 D=0 

160 INTEGER I1[20] 

170 REM: 11[#*]=TAG FIELD 

180 REM: ----- LOCAL VARIABLES----- 

190 DIM N1$[(20] ,N2$[20] ,A1$ [20] 

200 REM: N1$,N2$=NAME; A1$=ADDRESS 

210 DIM NO$[20,20] ,AO$[20, 20] 

220 REM: NO$,AO$=LIST OF NAMES AND ADDRESSES 
225 DIM B$[20] 

226 REM: B$= BLANK PADDING STRING 

230 INTEGER P,S | 

240 REM: P=LAST RECORD POINTER; S=STATUS 

250 INTEGER X 








255 X=0 

256 S=1 

BOO REM: st te at 96 a a8 96 46 96 26 a a8 He HE aE 2 He aE 2 ee 2 8 HE 9 He a EE HE EH A Ea ak HH Ha a 
810 REM: START OF PROGRAM 


UMA LOLLC CLEC LL LOCeCCLOLLLCCCLeerrrrrrerrroeeer rere nen ent) 
830 CALL BGET(C,F,11[*] ) 

845 IF C<>0 THEN GOTO 7000 

850 GOSUB 5000 

870 GOSUB F OF 1000,2000,3000, 4000 

880 GOTO 800 

LUQQOQMIA CIELO LIL TT tirrrrrirrirrrrrrrirrrrrrrrrrTrrrTrerrr yy 
1010 REM: BPOPEN 

DAMS MCL TTT Tri T it rrirririrrrrrrrrrrrrrrrrrrrrr rrr terre Ty 
1030 CALL BACCEPT(C,F) 

1050 GOSUB 5000 

1055 REM: INITIALIZE NAME AND ADDRESS ARRAYS 

1056 B$=" ’ 

1060 FOR P=1 TO 9 

1070 READ NO$[P] ,AO$[P] 

1074 REM: PAD STRINGS WITH BLANKS 

1075 NO$[P]=NO$[P]+B$ 

e 1076 AO$[P]=A0$[P]+B$ 
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1080 
1085 
1090 
2000 
2010 
2020 
2030 
2040 
2050 
2060 
2070 
2080 
2090 
2100 
2110 
2120 
2130 
2140 
2150 
2160 
2170 
3000 
3010 
3020 
3030 
3035 
3040 
3050 
3055 
3060 
3070 
3080 
3090 
3100 
3110 
3120 
3130 
3140 
3150 
3160 
3170 
3180 
3190 
3200 
3210 
3220 
3230 
3240 
3250 
3260 
3270 
3280 
3290 
3300 


NEXT P 
P=9 

RETURN 

REM © 46 4G 6 SE HE OE 90 46 16 46 96 0 96 46 8 90 46 56 46 4 56 46 46 OE SE 46 96 46 56 5E 96 96 96 46 46 06 46 9b 46 OE 46 26 0b 46 46 06 46 46 46 20 96 96 16 
REM: READ 

REM ¢ 94-96 96 96 96 96 96 96 46-46 96 96 56 2 40 46 96 6 96 96 26 96 6 46 SE 96 9b HE 06 UE SE 6 HE HE 46 96 46 0 9b 44 46 aE 06 OE HE HE 6 OE 58 96 HE HE 06 


IF I11[1]=2 THEN GOTO 2090 


REM: ### LIST SINGLE RECORD ### 

Ti[1]=S=1 

CALL BACCEPT(C,F,11[#],NO$[PO] ,A0$[PO] ) 

GOSUB 5000 

RETURN 

REM: ###LIST ALL RECORDS ### 

IF S<>0 THEN PO=0 

S=0 

PO=P0+1 

IF PO=P THEN S=1 

11[1]=s 

CALL BACCEPT(C,F,11[#] ,NO$[PO] ,AO0$[PO] ) 

GOSUB 5000 

RETURN 

REM © 4b 4G Ob 46 HE Mb 9t HE HE HE Ob aE OE OE HE HE HE 4G 2E HE 5E HE 46 HE 96 46 9 48 96 OE OE 4E HE HE HE OE 5H 9E HE OE 98 46 EOE SE 4 4E HE 6 06 OE HE EE 
REM: WRITE 

REM © Ot HE HE Ob HE OE Hb HE HE HE HE Et HE 6 8 9G 48 26 48 8 0G 4b Eat Oe St HE OE HE HE HE HE 9G OE GE SE aE 9G HE 2E 58 Hb at OE OE 4 9 OE 20 4 OE 


GOSUB 11[1] OF 3040,3160,3290,3410 


RETURN 

REM: ###ENTRY: NAME CHANGE ### 
CALL BACCEPT(C,F,11[#] ,.N1$,N2$) 
GOSUB 5000 

PO=0 

PO=PO+1 

IF NO$[PO]=N1$ THEN GOTO 3120 
IF PO<>P THEN GOTO 3070 

S=-1 

RETURN 

REM: ### NAME FOUND, CHANGE IT ### 


NO$ [PO] =N2$ 

S=1 

RETURN 

REM: ###ENTRY: ADDRESS CHANGE ### 
CALL BACCEPT(C,F,0,N1$,A1$) 

GOSUB 5000 

PO=0 

PO=P0+1 

IF NO$[PO]=N1$ THEN GOTO 3250 

IF PO<>P THEN GOTO 3200 

S=-1 

RETURN 

REM: *## RECORD FOUND, CHANGE IT ##+# 
AO$[POJ=A1$ 

S=1 

RETURN 


REM: ###ENTRY: INSERT NAME 
CALL BACCEPT(C,F,0,N1$,A1$) 
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3310 GOSUB 5000 

3320 IF P=20 THEN GOTO 3380 

3330 P=P+1 

3340 NO$[P]=N1$ 

3350 AO$[P]=A1$ 

3360 S=1 

3370 RETURN 

3380 REM: *##LIST ALREADY FULL ### 
3390 S=-1 

3400 RETURN 

3410 REM: ### ENTRY: DELETE NAME ### 
3420 CALL BACCEPT(C,F,0,N1$) 

3430 GOSUB 5000 

3440 PO=0 

3450 PO=P0+1 

3460 IF NO$[PO]=N1$ THEN GOTO 3500 
3470 IF PO<>P THEN GOTO 3450 

3480 S=-1 





eo 3490 RETURN 
3500 REM: ###FOUND RECORD, DELETE IT ##+# 
3510 NO$[PO] =B$ 
3515 AO$[PO]=B$ 
3520 S=1 
3530 RETURN 
4000 REM ¢ 4 46 46 at 46 98 96 56 Hb ab 46 at 4b a 46 SE SE ab 6 9E He HE OE HE 2b SEE SE 2E 6 aE 9G HE HE 46 2 dE OE 24 96 46 0 HE 46 96 48 96 26 46 28 2 28 08 2 
4010 REM: BPCONTROL 
4020 REM ¢ 964 96 26 46 46 44 96 96 Ot 56 0 4b 6 He HE ae 6 9E 96 26 0b OE 9E 6 aE HEE 96 HE 9E 96 96 Be 46 HE aE 48 96 HE HE 96 9b 98 26 HE OE 2b 96 96 26 96 96 HE 
4030 11[1]=S 
4040 CALL BACCEPT(C,F,11[#]) 
4050 RETURN 
5000 PREM ¢ 44 46 46 4 6 46 26 5 96 46 46 aE ae a 96 46 SE He ae 96 HE OE 96 5b 6 OF 96 OE 96 Ete 96 48 96 9b HE 4E OF aE aE 96 2 OE 8 96 6 26 28 2e 9E 28 0 08 
5010 REM: CONDITION CODE AND STATUS CHECK 
FOLD REM: 44646 46 46 6 4 46 46 56 46 46 46 96 ae 9b ab 96 ab 46 He HE 46 6 44 4G HE 96 OE 98 aE 44 9e 4E aE HE HE HE 6 26 HE 96 OE 96 96 2 8 at 96 96 96 96 28 28 
5030 IF C>0 THEN GOTO 5070 
5040 IF C<O THEN GOTO 5100 
5050 REM: ###EVERYTHING OKAY ### 
S060 RETURN 
SO70 REM: ### CCG ERROR ### 
S080 PRINT "### SLAVE: PTOP(CCG) ###" 
5090 RETURN 
5100 REM: ### CCL ERROR ### 
5110 I=0 
5120 CALL BPCHECK(C,I,I0) 
5130 PRINT “### SLAVE: PTOP ERROR: ";I0;" ###" 
5140 RETURN 
6000 DATA "CHRISTINE", "BRISTOL" 
6010 DATA "MEL" ,"CAMBRIDGE" 
6020 DATA "CAROL","PALO ALTO" 
6030 DATA "LISA, MISA & RICHIE", BRISTOL" 
6040 DATA "LISBET","ZURICH" 
6050 DATA "JOHN", BERKELEY" 
6060 DATA "CAROLYN" ,"ST. PAUL" 
6070 DATA "TODD","SANTA CLARA" 
6080 DATA "GARY","SAN FRANCISCO” 
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7000 CALL REJECT(C,11[*]) 
7010 GOTO 830 
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055000 


060400 
061000 
061400 
062000 
062400 
063000 
063400 
064000 
064400 
065000 
065400 
066000 
066400 
067000 
067400 
070000 
070400 
071000 
071400 
072000 
072400 
073000 
073400 
074000 
074400 
075000 


030000 
030400 
031000 
031400 
032000 
032400 
033000 
033400 
034000 
034400 


000000 
000400 
001000 
001400 
002000 
002400 


060101 
000102 
000103 
000104 
000105 
000106 
000107 
000110 
000111 
000112 
000113 
000114 
000115 
000116 
000117 
000120 
000121 
000122 
000123 
000124 
000125 
000126 
000127 
000130 
000131 
000132 


000141 
000142 
000143 
000144 
000145 
000146 
000147 
000150 
000151 
000152 
000153 
000154 
000155 
000156 
000157 
000160 
000161 
000162 
000163 
000164 
000165 
000166 
000167 
000170 
000171 
000172 


000060 
000061 
000062 
000063 
000064 
000065 
000066 
000067 
000070 
000071 
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003000 
003400 
004000 
004400 
005000 
005400 
006000 
006400 
007000 
007400 
010000 
010400 
011000 
011400 
012000 
012400 
013000 
013400 
014000 
014400 
015000 
015400 
016000 
016400 
017000 
017400 
020000 
020400 
021000 
021400 
022000 
022400 
023000 
023400 
024000 
024400 
025000 
025400 
026000 
026400 
027000 
027400 
035000 
035400 
036000 
036400 
037000 
037400 
040000 
055400 
056000 
056400 
057000 
057400 
060000 
075400 
076000 
076400 
077000 
077400 


First Character 


APPENDIX 


000006 
000007 
000010 
000011 
000012 
000013 
000014 
000015 
000016 
000017 
000020 
000021 
000022 
000023 
000024 
000025 
000026 
000027 
000030 
000031 
000032 
000033 
000034 
000035 
000036 
000037 
000040 
000041 
000042 
000043 
000044 
000045 
000046 
000047 
000050 
000051 
000052 
000053 
000054 
000055 
000056 
000057 
000072 
000073 
000074 
000075 
000076 
000077 
000100 
000133 
000134 
000135 
000136 
000137 
000140 
000173 
000174 
000175 
000176 
000177 
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ACCEPT, 6-3, 6-4, 6-6 
and GET, 6-7 
and PCONTROL, 6-6, 6-7 
and POPEN, 6-6, 6-7 
and PREAD, 6-6, 6-7 
and PWRITE, 6-6, 6-7 
condition codes, 6-7 
operation, 6-7 
parameters, 6-6 
syntax, 6-6 
Accessing data bases with data base-access file, 5-14 
Acctname, 2-30 
Acctpass, 2-30 
ACTIVATE, 6-4 
Activating a data base-access file, 5-12 
Autodial, 2-6 








BACCEPT, C-5 
BASIC 
and DSCOPY intrinsic, 7-16 
and DSCOPYMSG intrinsic, 7-18 

ca Batch job, using remote subsystem from, 3-4 
<< Bell 201, 2-5 
Bell 208, 2-5 
Bell 209, 2-5 
BGET, C-5 
Blocking control, 8-2 
Blocking factor, 2-3, 2-6 
BPCHECK, C-6 
BPCLOSE, C-5 
BPCONTROL, C-4 
BPOPEN, C-3 
BPREAD, C-4 
BPWRITE, C-4 
BREAK 

and DSCOPY, 7-5 

and DSCOPYMSG, 7-13 

and Network File Transfer, 7-5 

and NFT, 7-5 

and remote sessions, 3-4 
BREJECT, C-6 
BS, 2-31 
Buffer length, 8-2 
Buffer size, 2-18, 5-7 
Buffers, line and continuation, 8-8 
BYE command 

within remote logon UDCs, 2-33, 3-9 
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Index 


Cc 


CACCEPT, B-5 
CGET, B-4 
CLOSE, 6-4 
Closing a line, 2-50 
COBOL 
and DSCOPY intrinsic, 7-15 
and DSCOPYMSG intrinsic, 7-17 
Commands 
issuing local, 3-7 
issuing remote, 3-1 
Communications link, 2-1 
COMP, 2-18 
Compression, 2-18, 8-10 
and DSCONTROL, 8-10 
and DSLINE, 8-10 
and I/O configuration, 8-10 
and SYSDUMP, 8-10 
formats, 8-11 
Continuation buffers, 8-9 
Control keys, and remote sessions, 3-6 
Coordinating master and slave programs, 8-3 
CPCHECK, B-5 
CPCLOSE, B-3 
CPCONTROL, B-3 
CPOPEN, B-2 
CPREAD, B-3 
Cpusecs, 2-31, 5-9 
CPWRITE, B-3 
CREATE, 6-4 
Creating a data base-access file, $-7 
CREJECT, B-5 
CS, 2-31 
CSHBSCO, 2-8 
CSSBSCO, 2-8 


D 


Data base-access file 
activating, 5-12 
creating, 5-7 
example, 5-11 
parameters, 5-7 
syntax, 5-7 

Data bases, accessing, 5-14 

DBA example, 5-11 


INDEX-2 


7, 











DBA file 
accessing data bases, 5-14 
activating, 5-12 
creating, 5-7 
parameters, 5-7 
syntax, 5-7 
Dbnamel, 5-7 
Dbname2, 5-7 
Debugging DS applications, 8-8 
DEV parameter, 4-1 
Device class name, 2-8 
Dialing the remote computer, 2-21 
Dialup line multiple user example, 2-25, 2-26, 2-27 
DISC, 4-1 
DMOVEIN, 6-4 
DMOVEOUT, 6-4 
DS, 2-31 
DS applications, 8-1 
debugging, 8-8 
DS header, 8-2 
DS line number, 2-4 
DS performance, 8-11 
and communication links, 8-11 
and remote listing, 8-12 
computer system dependent, 8-1 | 
DS/3000 BASIC interface, C-1 
and string variables, C-1 
common parameters, C-1 
conventions, C-1 
example, C-6 
DS/3000 BASIC interface intrinsics, C-3 
DS/3000 COBOL interface, B-1 
common parameters, B-1 
conventions, B-1 
example, B-5 
DS/3000 COBOL interface intrinsics, B-2 
DS/3000 functional errors, A-3 
DSCONTROL, 9-1 
and compression, 8-10 
command execution order, 9-5 
error messages, A-6 
examples, 9-7 
informatory messages, A-6 
operation, 9-5 
syntax, 9-2 
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Index 


Index 





DSCOPY, 7-1 
and Back-Referenced Files, 7-6 
and BREAK, 7-5 
and File Equations, 7-6 
and KSAM files, 7-5 
and negative file codes, 7-5 
BASIC example, 7-20 
BASIC intrinsic, 7-16 
COBOL example, 7-19 
COBOL intrinsic, 7-15 
ending interactive mode, 7-11 
event recording, 7-12 
FORTRAN example, 7-19 
FORTRAN intrinsic, 7~15 
general error messages, A-9 
interactive mode, 7-11 
internal errors, A-1 1 
multiple requests, 7-3 
multiple transactions, 7-11 
operation, 7-5 
parameters, 7-3 
Pascal example, 7-20 
Pascal intrinsic, 7-16 
programmatic mode, 7-13 
source and target files, 7-5 
- SPL intrinsic, 7-13 
SPL/3000 example, 7-20 
SPL/3000 intrinsic, 7-16 
syntax, 7-3 
use, 7-4 
DSCOPY intrinsic, error returns, A-10 
DSCOPYI, multiple transactions, 7-11 
DSCOPYMSG, 7-13 
and BREAK, 7-13 
BASIC intrinsic, 7-18 
COBOL data types, 7-13 
COBOL intrinsic, 7-17 
FORTRAN intrinsic, 7~17 
Pascal data types, 7-13 
Pascal intrinsic, 7-18 
SPL/3000 intrinsic, 7-16, 7-18 
Dsdevice, 2-17, 2-31, 5-7 
Dsdevice parameter 
with FILE, 4-1 
with FOPEN, 4-15 
DSLINE, 2-17, 2-50 
and compression, 8-10 
examples, 2-51 
parameters, 2-17 
syntax, 2-17 
DSLINE syntax errors, A-1 
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Entering remote mode, 3-6 
Error messages, A-1 
Errors 
at line opening, 2-48 
at opening dialup line, 2-49 
DS/ 3000 functional, A-3 
DSCONTROL, A-6 
DSCONTROL informatory, A-6 
DSCOPY general messages, A-9 
DSCOPY internal, A-1 1 
DSCOPY intrinsic, A-10 
DSLINE syntax, A-1 
X.21 call progress signals, A-11 
X.21 DCE provided information, A-12 
X.21 messages, A-1 1 
ES, 2-31 
Establishing a remote link 
dialup example, 2-40 
hardwired example, 2-36 
X.25 example, 2-45 
Establishing a second remote link 
dialup example, 2-42 
hardwired example, 2-37 
X.25 example, 2-47 
Examples 
BASIC DSCOPY, 7-20 
COBOL DSCOPY, 7-19 
data base-access file, 5-11 
DBA, 5-11 
dialup line multiple user, 2-25, 2-26, 2-27 
DS/3000 BASIC interface, C-6 
DS/3000 COBOL interface, B- 5 
DSCONTROL, 9-7 
DSCOPY, 7-6 
DSLINE, 2-51 
establishing a remote line dialup, 2-40 
establishing a remote line X.25, 2-45 
establishing a second remote link dialup, 2-42 
establishing a second remote link hardwired, 2-37 
establishing a second remote link X.25, 2-47 
establishing a remote line hardwired, 2-36 
exclusive option, 2-24 
FCOPYing to a remote system, 4-8 
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Index 


Index 


FORTRAN DSCOPY, 7-19 
initiating the local session dialup, 2-39 
initiating the local session X.25, 2-44 
initiating the local session hardwired, 2-35 
locally running remote programs, 4-10 
locally sorting a remote file, 4-5 
multiple line dialup, 2-38 
multiple line hardwired, 2-34 
multiple line X.25, 2-43 
multiple user, 2-23 
multiple user dialup line, 2-25, 2-26, 2-27 
Network File Transfer, 7-6 
NFT, 7-6 
Pascal DSCOPY, 7-20 
programmatic access, 4-17 
programmatic DSCOPY, 7-19 
PTOP, 6-25 
PTOP master program, 6-25 
PTOP slave program, 6-27 
remote off-line listing, 4-3 
remote programs and local data, 4-13 
SPL/3000 DSCOPY, 7-20 
Exclusive, 2-18, 2-22, 5-8 
Exclusive option example, 2-24 
Execution priority, 5-9 


F 


Failures 
dialup line opening, 2-49 
line opening, 2-48 
FCHECK, 6-4 
FCLOSE, 6-4 
FCONTROL, 6-4 
FCOPYing to a remote system, 4-8 
FOPEN, 6-4 
FORTRAN 
and DSCOPY intrinsic, 7-15 
and DSCOPYMSG intrinsic, 7-17 
FREAD, 6-4 
FWRITE, 6-4 
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G 


GET, 6-3, 6-4, 6-8 
and ACCEPT, 6-7 
and IOWAIT, 6-9 
and PREAD, 6-8 
and PWRITE, 6-8 
condition codes, 6-9 
functional return, 6-8 
operation, 6-9 
parameters, 6-8 
syntax, 6-8 

GETDSEG, 6-4 

Groupname, 2-30 


H 


Hardwired line, opening, 2~2 

Hardwired Serial Interface, 2-2, 2-5, 2-8, 2-18 

HIPRI, 2-29, 2-31, 5-10 

Home group, 2-30 

HP 3000 Series 30/33/39/40/42/44/48, 2-2, 2-5 

HP 3000 Series 30/33/39/40/42/44/48/64/68, 2-2, 2-5 

HP 3000 Series II/III, 2-2, 2-5 

HP 30010A, 2-2, 2-5 

HP 30020A, 2-2, 2-5 

HP 30020B, 2-2, 2-5 
2~5 


HP 30055A, 2-2, 
HP 30360A, 2-2 
HP 32710T, 2-5 


HP 37220T, 2-5 
HP 37230A, 2-5 
HSI, 2-2, 2-5, 2-8, 2-18 
hardwired sample I/O device table, 2-8 
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Index 


Index 


I/O configuration, and compression, 8-10 
ID sequences, 2-21, 2-28 
Initiating the local session 
dialup example, 2-39 
hardwired example, 2-35 
X.25 example, 2-44 
INP, 2-2, 2-5, 2-8, 2-18 
dialup sample I/O device table, 2-14 
hardwired sample I/O device table, 2-10 
Input priority, 5-9 
Inputpriority, 2-31 
Intelligent Network Processor, 2-2, 2-5, 2-8, 2-18 
Interactive access, 4-1 
Interactive mode, ending, 7-11 
Interactive Mode, entering MPE commands, 7-1! 1 
Interprocess Communications, 1-1, 6-1, 8-1 
advantage over PTOP, 8-8 
and PTOP, 8-4 
Intrinsics 
PTOP, 6-5 
PTOP ACCEPT, 6-6 
PTOP GET, 6-8 
PTOP PCHECK, 6-10 
PTOP PCLOSE, 6-11 
PTOP PCONTROL, 6-12 
PTOP POPEN, 6-14 
PTOP PREAD, 6-20 
PTOP PWRITE, 6-22 
PTOP REJECT, 6-24 
IODSO, 2-8 
IODSTRMO, 2-8 
IODSTRMxX, 2-8 
IODSX, 2-8, 2-17 
IOINPO, 2-8 
IOWAIT, and GET, 6-9 
IPC, 1-1, 6-1, 8-1 
advantage over PTOP, 8-8 
and PTOP, 8-4 
Issuing local commands, 3-7 
Issuing remote commands, 3-1 
I/O configuration, and compression, 8-10 
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KILL, 6-4 

KSAM files 
and DSCOPY, 7-5 
and Network File Transfer, 7-5 
and NFT, 7-5 


L 


Lacctname, 5-8 
LDEV, 2-8 
LDN, 2-8 
Lgroupname, 5-8 
Line and continuation buffers, 8-8 
Line buffer, 2-3, 2-6 
Line number, 3-2 
Line opening failures, 2-48 

dialup, 2-49 
Local, 1-3 
Local commands, issuing, 3-7 
Local ID sequence, 2-19, 5-7 
Locally running remote programs, 4-10 
Locally sorting a remote file, 4-5 
Logical device number, 2-8 
Lusername, 5-8 


Master PTOP intrinsics, 6-2 
Message Switching Procedure, 8-7 
Modem, 2-5 
Modulator-demodulator, 2-5 
MPE commands 

comparison with PTOP, 6-4 

entering during Interactive mode, 7-11 
MSP, 8-7 
Multiple data bases, and RDBA, 5-3 
Multiple DSCOPY requests, 7-11 
Multiple line example 

dialup, 2-38 

hardwired, 2-34 

X.25, 2-43 
Multiple remote access, 8-13 
Multiple user dialup line example, 2-25, 2-26, 2-27 
Multiple user example, 2-23 
Multiple users, 2-22 
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Index 


Index 


Network File Transfer, 1-1, 7-1, 8-1 


and BREAK, 7-5 

and KSAM files, 7-5 

and negative file codes, 7-5 
consuming system, 7-1 
DSCOPY operation, 7-5 
DSCOPY parameters, 7-3 
DSCOPY syntax, 7-3 
DSCOPY use, 7-4 

ending interactive mode, 7-11 
event recording, 7-12 
features, 7-1 

initiating system, 7-1 
interactive mode, 7-11 
multiple DSCOPY requests, 7-11 
producing system, 7-1 
programmatic mode, 7-13 
source and target files, 7-5 


NFT, 1-1, 7-1, 8-1 


and BREAK, 7-5 

and KSAM files, 7-5 

and negative file codes, 7-5 
consuming system., 7-1 
DSCOPY operation, 7-5 
DSCOPY parameters, 7-3 
DSCOPY syntax, 7-3 

DSCOPY use, 7-4 

ending interactive mode, 7-11 
event recording, 7-12 

features, 7-1 

initiating system, 7-1 
interactive mode, 7-11 
multiple DSCOPY requests, 7-3 
multiple transactions with DSCOPYI, 7-11 
producing system, 7-1 
programmatic mode, 7-13 
source and target files, 7-5 


Nocomp, 2-18 
Node name, 2-31 


0 


Opening a hardwired line, 2-2 
Opening a line, 2-2 


with Remote Hello, 2-31 


Opening a telephone line, 2-5 
Opening multiple lines, 2-34 
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P 


Pascal 
and DSCOPY intrinsic, 7-16 
and DSCOPYMSG intrinsic, 7-18 

PCHECK, 6-2, 6-3, 6-4, 6-10 
condition codes, 6-10 
functional return, 6-10 
operation, 6-10 
parameters, 6-10 
syntax, 6-10 

PCLOSE, 6-2, 6-11 
condition codes, 6-11 
operation, 6-11 
parameters, 6-11 
syntax, 6-11 

PCONTROL, 6-2, 6-4, 6-12 
and ACCEPT, 6-6, 6-7 
condition codes, 6-12 
operation, 6-12 
parameters, 6-12 
syntax, 6-12 

PDN, 2-17 

PHONELIST, 2-21 

POPEN, 6-2, 6-4, 6-14 
and ACCEPT, 6-6, 6-7 
condition codes, 6-18 
functional return, 6-14 
operation, 6-18 
parameters, 6-14 
syntax, 6-14 

PORTMASK, 2-8 

PREAD, 6-2, 6-4, 6-20 
and ACCEPT, 6-6, 6-7 
and GET, 6-8 
condition codes, 6-20 
functional return, 6-20 
operation, 6-21 
parameters, 6-20 
syntax, 6-20 

Program-to-program communications, see PTOP 

Programmatic access, 4-15 
example, 4-17 
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Index 


PTOP, 1-1, 6-1, 8-1 
advantages of, 8-1 
and SPL, 6-5 
example, 6-25 
interfacing with BASIC and COBOL, 6-25 
interfacing with COBOL and BASIC, 6-25 
master intrinsics, 6-2 
slave intrinsics, 6-3 
PTOP commands, comparison with MPE, 6-4 
PTOP intrinsics, 6-5 
ACCEPT, 6-6 
GET, 6-8 
PCHECK, 6-10 
PCLOSE, 6-11 
PCONTROL, 6-12 
POPEN, 6-14 
PREAD, 6-20 
PWRITE, 6-22 - 
REJECT, 6-24 
PWRITE, 6-2, 6-4, 6-22 
and ACCEPT, 6-6, 6-7 
and GET, 6-8 
condition codes, 6-22 
operation, 6-22 
parameters, 6-22 
syntax, 6-22 








Q 


QUERY, 5-15 
Quiet, 2-18, 5-8 


R 


Racctname, 5-9 
Rapasw, 5-9 
RDBA, 1-1, 5-1 
through a local application program, 5-2 
using a data base-access file, 5-5 
using a DBA file, 5-5 
using the command intrinsic, 5-3 
with multiple data bases, 5-3 
RECEIVEMAIL, 6-4 
REJECT, 6-3, 6-4, 6-24 
condition codes, 6-24 
operation, 6-24 
parameters, 6-24 
syntax, 6-24 
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Remote, 1-4 
REMOTE, 3-2 
Remote Command Execution, 1-1 
Remote commands, issuing, 3-1 
Remote Data Base Access, 1-1, 5-1 
Remote File Access, 1-1, 4-1, 8-1 
Remote Hello, 2-29 

for opening a line, 2-31 

parameters, 2-30 

syntax, 2-29 
Remote ID sequence, 2-19, 5- 
Remote logon UDCs, 2-33, 3- 
Remote mode, entering, 3-6 
Remote off-line listing, 4-3 
Remote programs and local data, 4-13 
Remote sessions, 3-1 

and BREAK, 3-4 

and CONTROL keys, 3-6 
RFA, 4-1, 8-1 
Rgpasw, 5-9 
Rupasw, 5-9 
Rusername, 5-9 
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Sample I/O device table, INP dialup, 2-14 
Sample I/O device tables, 2-8 

HSI hardwired, 2-8 

INP hardwired, 2-10 

SSLC dialup, 2-12 
SELECT, 2-19 
Selection signal sequence, 2-19 
SENDMAIL, 6-4 
Sessionname, 2-30 
Single system/distributed system comparison, 6-4 
Slave PTOP intrinsics, 6-3 
Specifying a DS line, 2-8 
Specifying an X.25 line, 2-16 
SPL/3000 

and DSCOPY intrinsic, 7-13, 7-16 

and DSCOPYMSG intrinsic, 7-18 

and PTOP, 6-5 
SSLC, 2~2, 2-5, 2-8, 2-18 

dialup sample I/O device table, 2-12 
Synchronous Single-Line Controller, see SSLC 
SYSDUMP, and compression, 8-10 
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Telephone line, 2-19 
opening, 2-5 
Telephone number, 2-19, 5-8 
TERMINATE, 6-4 
Terminating remote session, 3-7 
from local session, 3-7 
from remote session, 3-8 
within remote logon UDCs, 2-33, 3-9 
Termtype, 2-30 
Time, 5-9 
Transmission between systems, 8-2 
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User identification, 5-11 

Username, 2-30 

Userpass, 2-30 

Using remote subsystem from batch job, 3-4 
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Virtual terminal, 1-1, 2-8 
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X.21 messages, A-1 1 

call process signals, A-1 1 

DCE provided information, A-12 
X.25, 2-17, 2-31 
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